#lang scribble/doc @(require scribble/manual (for-label scheme "../data.ss" "../interface.ss")) @title[#:tag "interface"]{Common Interfaces} @local-table-of-contents[] @defmodule[(planet "interface.ss" ("murphy" "9p.plt" 1 0))]{ This module contains interfaces that are implemented both on the client and server side of the 9P protocol. Client and server side file and directory handle objects can be used interchangeably if they are only accessed through these interfaces. } @definterface[filesystem<%> ()]{ @defmethod[(authenticate [root string?] [#:user user string?]) (is-a?/c file-handle<%>)]{ Opens an authentication channel suitable as a token when attaching to the filesystem root directory @scheme[root] as the given @scheme[user]. This method may raise an exception if the filesystem does not require authentication. If an authentication channel is returned, it will likely be necessary to complete some challenge response protocol over that channel before it can be used as an authentication token. } @defmethod[(attach [root string?] [#:user user string?] [#:token auth (or/c (is-a?/c file-handle<%>) #f)]) (is-a?/c directory-handle<%>)]{ Opens the filesystem root directory @scheme[root] as the given @scheme[user]. Authentication context is optionally provided by the file handle @scheme[auth]. } @defmethod[(clunk) void?]{ Drops the connection to the whole filesystem. } } @definterface[file-handle<%> ()]{ @defmethod[(walk [name string?] ...) (is-a?/c file-handle<%>)]{ Moves from the file represented by this handle to a different file and returns a file handle for the target. The given @scheme[name] arguments define the path to take to the target: @scheme[".."] stands for the parent directory of the current file, any other string is the name of a file or directory to move to. You can usually walk from any file to itself calling walk with no arguments or to its parent directory calling walk with a single @scheme[".."] argument, but walking to named children normally only works for directories. } @defmethod[(read-stat) stat?]{ Obtains the directory entry information for a file. } @defmethod[(write-stat [stat stat?]) void?]{ Changes the directory entry information for a file. Only the fields @scheme[stat-mode], @scheme[stat-mtime], @scheme[stat-length], @scheme[stat-name] and @scheme[stat-gid] can be changed at all, any other field should be set to @scheme[#f]. The directory bit in the @scheme[stat-mode] field cannot be changed. The @scheme[stat-length] field, if it is set at all, can only be set to zero, truncating the file. In addition to the basic parameter validation, the file server may perform permission checks to determine if a change is allowed. If the method does not raise an exception, all of the requested changes have been performed by the file server, otherwise nothing should have changed. } @defmethod[(open [mode natural-number/c]) natural-number/c]{ Opens the file for reading or writing data and returns the maximum I/O unit size. The @scheme[mode] argument is a combination of flags as it can be produced by the @scheme[open-mode] macro. } @defmethod[(read [size natural-number/c] [offset natural-number/c]) (or/c bytes? eof-object?)]{ Reads data from the file after it has been opened for reading. The returned data should be at most @scheme[size] bytes long. } @defmethod[(write [data bytes?] [offset natural-number/c]) natural-number/c]{ Writes data to the file after it has been opened for writing. The return value is the number of bytes actually written. } @defmethod[(clunk) void?]{ Closes the file if it is open and invalidates the file handle. Even if this method signals an error, the file handle is still invalid after the call. } @defmethod[(remove) void?]{ Closes the file if it is open, removes it from the storage device and invalidates the file handle. Even if this method signals an error, the file handle is still invalid after the call. } } @definterface[directory-handle<%> (file-handle<%>)]{ @defmethod[(in-entries) sequence?]{ Returns an iterable sequence of directory entries. } @defmethod[(create [name string?] [perm natural-number/c] [mode natural-number/c]) (values (is-a?/c file-handle<%>) natural-number/c)]{ Creates a new entry in the directory. The type of the new file and its access permissions are determined by @scheme[perm]. You can pass a value computed using the macro @scheme[file-mode] here. If the newly created file is not a directory, it is immediately open for I/O operations with the given @scheme[mode]. The open mode is @emph{not} checked against the permissions of the new file. You can pass a value computed using the macro @scheme[open-mode] here. In case of success, the method returns both a new file handle and an I/O unit value. } }