1 /*
2  * Copyright (C) 2023 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 com.android.net.module.util.wear;
18 
19 /**
20  * Defines bidirectional file where all transmissions are made as complete packets.
21  *
22  * Automatically manages all readability and writeability events in EventManager:
23  *   - When read buffer has more space - asks EventManager to notify on more data
24  *   - When write buffer has more space - asks the user to provide more data
25  *   - When underlying file cannot accept more data - registers EventManager callback
26  *
27  * @hide
28  */
29 public interface PacketFile {
30     /** @hide */
31     public enum ErrorCode {
32         UNEXPECTED_ERROR,
33         IO_ERROR,
34         INBOUND_PACKET_TOO_LARGE,
35         OUTBOUND_PACKET_TOO_LARGE,
36     }
37 
38     /**
39      * Receives notifications when new data or output space is available.
40      *
41      * @hide
42      */
43     public interface Listener {
44         /**
45          * Handles the initial part of the stream, which on some systems provides lower-level
46          * configuration data.
47          *
48          * Returns the number of bytes consumed, or zero if the preamble has been fully read.
49          */
onPreambleData(byte[] data, int pos, int len)50         int onPreambleData(byte[] data, int pos, int len);
51 
52         /** Handles one extracted packet. */
onInboundPacket(byte[] data, int pos, int len)53         void onInboundPacket(byte[] data, int pos, int len);
54 
55         /** Notifies on new data being added to the buffer. */
onInboundBuffered(int newByteCount, int totalBufferedSize)56         void onInboundBuffered(int newByteCount, int totalBufferedSize);
57 
58         /** Notifies on data being flushed from output buffer. */
onOutboundPacketSpace()59         void onOutboundPacketSpace();
60 
61         /** Notifies on unrecoverable error in the packet processing. */
onPacketFileError(ErrorCode error, String message)62         void onPacketFileError(ErrorCode error, String message);
63     }
64 
65     /** Requests this file to be closed. */
close()66     void close();
67 
68     /** Permanently disables reading of this file, and clears all buffered data. */
shutdownReading()69     void shutdownReading();
70 
71     /** Starts or resumes async read operations on this file. */
continueReading()72     void continueReading();
73 
74     /** Returns the number of bytes currently buffered as input. */
getInboundBufferSize()75     int getInboundBufferSize();
76 
77     /** Returns the number of bytes currently available for buffering for output. */
getOutboundFreeSize()78     int getOutboundFreeSize();
79 
80     /**
81      * Queues the given data for output.
82      * Throws runtime exception if there is not enough space.
83      */
enqueueOutboundPacket(byte[] data, int pos, int len)84     boolean enqueueOutboundPacket(byte[] data, int pos, int len);
85 }
86