/*
 * Copyright (C) 2016 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package android.os;

import android.system.ErrnoException;
import android.system.OsConstants;

Callback that handles file system requests from ProxyFileDescriptor. All callback methods except for onRelease should throw ErrnoException with proper errno on errors. See errno(3) and OsConstants. Typical errnos are 

EIO.EIO for general I/O issues 
ENOENT.ENOENT when the file is not found 
EBADF.EBADF if the file doesn't allow read/write operations based on how it was opened. (For example, trying to write a file that was opened read-only.) 
ENOSPC.ENOSPC if you cannot handle a write operation to space/quota limitations. 
See Also:
StorageManager.openProxyFileDescriptor(int, ProxyFileDescriptorCallback, Handler)/**
 * Callback that handles file system requests from ProxyFileDescriptor.
 *
 * All callback methods except for onRelease should throw {@link android.system.ErrnoException}
 * with proper errno on errors. See
 * <a href="http://man7.org/linux/man-pages/man3/errno.3.html">errno(3)</a> and
 * {@link android.system.OsConstants}.
 *
 * Typical errnos are
 *
 * <ul>
 * <li>{@link android.system.OsConstants#EIO} for general I/O issues
 * <li>{@link android.system.OsConstants#ENOENT} when the file is not found
 * <li>{@link android.system.OsConstants#EBADF} if the file doesn't allow read/write operations
 *     based on how it was opened.  (For example, trying to write a file that was opened read-only.)
 * <li>{@link android.system.OsConstants#ENOSPC} if you cannot handle a write operation to
 *     space/quota limitations.
 * </ul>
 * @see android.os.storage.StorageManager#openProxyFileDescriptor(int, ProxyFileDescriptorCallback,
 *     Handler)
 */
public abstract class ProxyFileDescriptorCallback {
    
Returns size of bytes provided by the file descriptor.
Throws:
ErrnoException – ErrnoException containing E constants in OsConstants.
Returns:
Size of bytes./**
     * Returns size of bytes provided by the file descriptor.
     * @return Size of bytes.
     * @throws ErrnoException ErrnoException containing E constants in OsConstants.
     */
    public long onGetSize() throws ErrnoException {
        throw new ErrnoException("onGetSize", OsConstants.EBADF);
    }

    
Provides bytes read from file descriptor.
It needs to return exact requested size of bytes unless it reaches file end.
Params:
offset – Offset in bytes from the file head specifying where to read bytes. If a seek
    operation is conducted on the file descriptor, then a read operation is requested, the
    offset refrects the proper position of requested bytes.
size – Size for read bytes.
data – Byte array to store read bytes.
Throws:
ErrnoException – ErrnoException containing E constants in OsConstants.
Returns:
Size of bytes returned by the function./**
     * Provides bytes read from file descriptor.
     * It needs to return exact requested size of bytes unless it reaches file end.
     * @param offset Offset in bytes from the file head specifying where to read bytes. If a seek
     *     operation is conducted on the file descriptor, then a read operation is requested, the
     *     offset refrects the proper position of requested bytes.
     * @param size Size for read bytes.
     * @param data Byte array to store read bytes.
     * @return Size of bytes returned by the function.
     * @throws ErrnoException ErrnoException containing E constants in OsConstants.
     */
    public int onRead(long offset, int size, byte[] data) throws ErrnoException {
        throw new ErrnoException("onRead", OsConstants.EBADF);
    }

    
Handles bytes written to file descriptor.
Params:
offset – Offset in bytes from the file head specifying where to write bytes. If a seek
    operation is conducted on the file descriptor, then a write operation is requested, the
    offset refrects the proper position of requested bytes.
size – Size for write bytes.
data – Byte array to be written to somewhere.
Throws:
ErrnoException – ErrnoException containing E constants in OsConstants.
Returns:
Size of bytes processed by the function./**
     * Handles bytes written to file descriptor.
     * @param offset Offset in bytes from the file head specifying where to write bytes. If a seek
     *     operation is conducted on the file descriptor, then a write operation is requested, the
     *     offset refrects the proper position of requested bytes.
     * @param size Size for write bytes.
     * @param data Byte array to be written to somewhere.
     * @return Size of bytes processed by the function.
     * @throws ErrnoException ErrnoException containing E constants in OsConstants.
     */
    public int onWrite(long offset, int size, byte[] data) throws ErrnoException {
        throw new ErrnoException("onWrite", OsConstants.EBADF);
    }

    
Ensures all the written data are stored in permanent storage device.
For example, if it has data stored in on memory cache, it needs to flush data to storage
device.
Throws:
ErrnoException – ErrnoException containing E constants in OsConstants./**
     * Ensures all the written data are stored in permanent storage device.
     * For example, if it has data stored in on memory cache, it needs to flush data to storage
     * device.
     * @throws ErrnoException ErrnoException containing E constants in OsConstants.
     */
    public void onFsync() throws ErrnoException {
        throw new ErrnoException("onFsync", OsConstants.EINVAL);
    }

    
Invoked after the file is closed.
/**
     * Invoked after the file is closed.
     */
    abstract public void onRelease();
}