/**
 * The [ProtocolTranslator] interface provides methods which represent, and enclose, full 9P transactions. A call to any
 * of such methods requires filling in parameters, which coincide one-to-one with fields required by 9P requests. In an
 * analogous way, the values returned from such methods calls reflects those received from 9P responses.
 *
 * Tags and the `msize` value are supposed to be managed internally by the implementing class.
 *
 * When compared to 9P's formal message descriptions, like those which can be read in Plan 9's manual pages, some of the
 * methods might lack parameters. Those which can be inferred from the existing parameters are purposefully omitted. An
 * example is [walk], which omits `nwname` because it can be obtained by calculating the size of `wname`.
 *
 * Trivia: comments for each method are taken from each message type's manual page in section 5.
 */
interface ProtocolTranslator {
    /**
     * Negotiate protocol version.
     *
     * This must be the first message sent on the 9P connection and no other requests can be issued until a response has
     * been received.
     *
     * @param msize The maximum length, in bytes, that the client will ever generate or expect to receive in a single
     *              9P message.
     * @param version Should be "9P2000", which is the only defined value.
     * @throws except.InvalidMessageException if the received message is invalid.
     * @throws except.RErrorException if the received message is an R-error message.
     * @throws except.MsizeValueTooBigException if the received `msize` value is bigger than what the client requested.
     * @throws except.UnknownVersionException if the version negotiation failed.
     */
    fun version(msize: UInt, version: String)

    /**
     * Perform authentication.
     */
    fun auth(afid: UInt, uname: String, aname: String)

    /**
     * Abort a message.
     *
     * @param oldtag The tag of the message that needs to be purged.
     * @throws except.InvalidMessageException if the received message is invalid.
     * @throws except.RErrorException if the received message is an R-error message.
     */
    fun flush(oldtag: UShort)

    /**
     * Establish a connection.
     *
     * @param fid FID that represents the root directory of the desired file tree.
     * @param afid A FID previously established by an auth message.
     * @param uname A user identifier.
     * @param aname The desired file tree to access.
     * @return The QID of the file tree's root.
     * @throws except.InvalidMessageException if the received message is invalid.
     * @throws except.RErrorException if the received message is an R-error message.
     */
    fun attach(fid: UInt, afid: UInt, uname: String, aname: String): QID

    /**
     * Descend a directory hierarchy.
     *
     * @param fid The existing FID. It must represent a directory.
     * @param newfid The proposed FID, which is going to be associated with the result of walking the hierarchy. It must
     * be not in use, unless it is the same as [fid].
     * @param wname The successive path name elements which describe the file to walk to.
     * @return The QID of each path element that has been walked through.
     * @throws except.InvalidMessageException if the received message is invalid.
     * @throws except.RErrorException if the received message is an R-error message.
     * @throws except.UnaccessibleFileException if [wname] contains one or more path elements that do not exist.
     */
    fun walk(fid: UInt, newfid: UInt, wname: List<String>): List<QID>

    /**
     * Prepare an FID for I/O on an existing file.
     *
     * @param fid The FID of the file to open.
     * @param mode The mode in which the file is opened.
     * @return A pair of: (1) the returned QID, and (2) a value called `iounit` that indicates, if non-zero, the maximum
     * number of bytes that are guaranteed to be read from or written to the file without breaking the I/O transfer into
     * multiple 9P messages.
     * @throws except.InvalidMessageException if the received message is invalid.
     * @throws except.RErrorException if the received message is an R-error message.
     */
    fun open(fid: UInt, mode: FileMode): Pair<QID, UInt>

    /**
     * Prepare an FID for I/O on a new file.
     *
     * @param fid The FID of the directory that is going to contain the file. The specified directory requires write
     * permission.
     * @param name The file name.
     * @param perm The permissions of the new file.
     * @param mode The open mode after successful creation.
     * @return A pair of: (1) the QID of the newly created file, and (2) a value called `iounit` that indicates, if
     * non-zero, the maximum number of bytes that are guaranteed to be read from or written to the file without breaking
     * the I/O transfer into multiple 9P messages.
     * @throws except.InvalidMessageException if the received message is invalid.
     * @throws except.RErrorException if the received message is an R-error message.
     */
    fun create(fid: UInt, name: String, perm: FilePermissions, mode: FileMode): Pair<QID, UInt>

    /**
     * Transfer data from file. Due to the negotiated maximum size of 9P messages, called `msize`, one is supposed to
     * call this method multiple times, unless the content is smaller than `msize`.
     *
     * @return The content read with the call just made.
     * @throws except.InvalidMessageException if the received message is invalid.
     * @throws except.RErrorException if the received message is an R-error message.
     */
    fun read(fid: UInt, offset: ULong, count: UInt): Array<UByte>

    /**
     * Transfer data to file. Due to the negotiated maximum size of 9P messages, called `msize`, this method is supposed
     * to be called multiple times, unless the content is smaller than `msize`.
     *
     * @param fid The FID to write to.
     * @param offset The distance between the beginning of the file and the first written byte.
     * @param data The raw bytes that are going to be written.
     * @return The amount of bytes written with the call just made.
     * @throws except.InvalidMessageException if the received message is invalid.
     * @throws except.RErrorException if the received message is an R-error message.
     */
    fun write(fid: UInt, offset: ULong, count: UInt, data: Iterable<UByte>): UInt

    /**
     * Forget about a FID.
     *
     * @param fid The FID to forget.
     * @throws except.InvalidMessageException if the received message is invalid.
     * @throws except.RErrorException if the received message is an R-error message.
     */
    fun clunk(fid: UInt)

    /**
     * Remove a file from a server.
     *
     * @param fid The FID of the file to remove.
     * @throws except.InvalidMessageException if the received message is invalid.
     * @throws except.RErrorException if the received message is an R-error message.
     */
    fun remove(fid: UInt)

    /**
     * Inquire file attributes.
     *
     * @param fid The FID of the file to inquire.
     * @return All the file attributes of the file associated with [fid].
     * @throws except.InvalidMessageException if the received message is invalid.
     * @throws except.RErrorException if the received message is an R-error message.
     */
    fun stat(fid: UInt): Stat

    /**
     * Change file attributes.
     *
     * @param fid The FID of the file to set attributes of.
     * @param stat The attributes to set.
     * @throws except.InvalidMessageException if the received message is invalid.
     * @throws except.RErrorException if the received message is an R-error message.
     */
    fun wstat(fid: UInt, stat: Stat)
}