| Version | Date | Change |
|---|---|---|
| 0.1 | 2008-01-10 | Initial contribution |
File System service provides file transfer (and more generally file system access) functionality in TCF. The service design is derived from SSH File Transfer Protocol specifications.
The protocol and implementations MUST process requests relating to the same file in the order in which they are received. In other words, if an application submits multiple requests to the server, the results in the responses will be the same as if it had sent the requests one at a time and waited for the response in each case. For example, the server may process non-overlapping read/write requests to the same file in parallel, but overlapping reads and writes cannot be reordered or parallelized. However, there are no ordering restrictions on the server for processing requests from two different file transfer connections. The server may interleave and parallelize them at will.
There are no restrictions on the order in which responses to outstanding requests are delivered to the client, except that the server must ensure fairness in the sense that processing of no request will be indefinitely delayed even if the client is sending other requests so that there are multiple outstanding requests all the time.
There is no limit on the number of outstanding (non-acknowledged) requests that the client may send to the server. In practice this is limited by the buffering available on the data stream and the queuing performed by the server. If the server's queues are full, it should not read any more data from the stream, and flow control will prevent the client from sending more requests.
This protocol represents file names as strings. File names are assumed to use the slash ('/') character as a directory separator.
File names starting with a slash are "absolute", and are relative to the root of the file system. Names starting with any other character are relative to the user's default directory (home directory). Client can use 'user()' command to retrieve current user home directory.
Servers SHOULD interpret a path name component ".." as referring to the parent directory, and "." as referring to the current directory. If the server implementation limits access to certain parts of the file system, it must be extra careful in parsing file names when enforcing such restrictions. There have been numerous reported security bugs where a ".." in a path name has allowed access outside the intended area.
An empty path name is valid, and it refers to the user's default directory (usually the user's home directory).
Otherwise, no syntax is defined for file names by this specification. Clients should not make any other assumptions; however, they can splice path name components returned by readdir() together using a slash ('/') as the separator, and that will work as expected.
File open mode is bitwise OR of mode flags:
TCF_O_READ = 0x00000001
TCF_O_WRITE = 0x00000002
TCF_O_APPEND = 0x00000004
TCF_O_CREAT = 0x00000008
TCF_O_TRUNC = 0x00000010
TCF_O_EXCL = 0x00000020
<file attributes>
⇒ <object>
All attributes are optional. Tools and targets can define additional attributes. Predefined attributes are:
"Size" : <int>
- file size in bytes
"UID" : <int>
- file owner user ID
"GID" : <int>
- file owner group ID
"Permissions" : <int>
- file access permissions
"ATime" : <int>
- file last access time
"MTime" : <int>
- file last modification time
The service uses standard format for error reports, see Error Report Format.
Currently, the following values are defined for service specific error codes (other values may be defined by future versions of this protocol):
STATUS_EOF = 0x10001
STATUS_NO_SUCH_FILE = 0x10002
STATUS_PERMISSION_DENIED = 0x10003
C • <token> • FileSystem • open • <string: file name> • <int: mode> • <file attributes> •
The command opens or creates a file on a remote system. If mode contains TCF_O_CREAT then new file is created, otherwise exsting file is opened. If the file is created, file attributes is looked up for UID, GID and permissions. If no attribute value is found in the command parameters, a default value is used.
Reply:
R • <token> • <error report> • <file handle> •
<file handle>
⇒ null
⇒ <string>
On success, the replay contains open file handle. The handle is encoded as a string of characters. Client should never try to decode the string, but should use it as is to issue further file access commands. Client should close the file when it is not needed any more. Server should close all files that were left open after client connection was closed ot terminated.
C • <token> • FileSystem • close • <string: file handle> •
The command closes a handle, which was open by 'open' or 'opendir' commands.
Reply:
R • <token> • <error report> •
C • <token> • FileSystem • read • <string: file handle> • <int: offset> • <int: size> •
The command reads bytes from an open file. In response to this request, the server will read as many bytes as it can from the file (up to `size'), and return them in a byte array. If an error occurs or EOF is encountered, the server may return fewer bytes then requested. Replay argument 'error report' will be not null in case of error, and argument 'eof' will be true in case of EOF. For normal disk files, it is guaranteed that this will read the specified number of bytes, or up to end of file or error. For e.g. device files this may return fewer bytes than requested.
If 'offset' < 0 then reading will start from current position in the file.
Reply:
R • <token> • <string: data> • <error report> • <boolean: eof> •
<string: data> is Base64 encoded byte array of file data. Number of bytes is determined by the string length. 'eof' is true when 'data' contains all available bytes up to the end of the file.
C • <token> • FileSystem • write • <string: file handle> • <int: offset> • <string: data> •
The command writes bytes into an open file. The write will extend the file if writing beyond the end of the file. It is legal to write way beyond the end of the file; the semantics are to write zeroes from the end of the file to the specified offset and then the data. <string: data> is Base64 encoded array of data bytes.
If 'offset' < 0 then writing will start from current position in the file.
Reply:
R • <token> • <error report> •
C • <token> • FileSystem • stat • <string: file name> •
The command retrieves file attributes.
Reply:
R • <token> • <error report> • <file attributes> •
C • <token> • FileSystem • lstat • <string: file name> •
The command retrieves file attributes. Unlike 'stat', 'lstat' does not follow symbolic links.
Reply:
R • <token> • <error report> • <file attributes> •
C • <token> • FileSystem • fstat • <string: file handle> •
The command retrieves file attributes for an open file (identified by the file handle).
Reply:
R • <token> • <error report> • <file attributes> •
C • <token> • FileSystem • setstat • <string: file name> • <file attributes> •
The command sets file attributes. This request is used for operations such as changing the ownership, permissions or access times, as well as for truncating a file. An error will be returned if the specified file system object does not exist or the user does not have sufficient rights to modify the specified attributes.
Reply:
R • <token> • <error report> •
C • <token> • FileSystem • fsetstat • <string: file handle> • <file attributes> •
The command sets file attributes for an open file (identified by the file handle). This request is used for operations such as changing the ownership, permissions or access times, as well as for truncating a file.
Reply:
R • <token> • <error report> •
C • <token> • FileSystem • opendir • <string: path> •
The command opens a directory for reading. Once the directory has been successfully opened, files (and directories) contained in it can be listed using 'readdir' requests. When the client no longer wishes to read more names from the directory, it SHOULD call 'close' for the handle. The handle should be closed regardless of whether a read errors have occurred or not.
Reply:
R • <token> • <error report> • <file handle> •
C • <token> • FileSystem • readdir • <string: file handle> •
The command returns one or more file names with full file attributes for each file. The client should call 'readdir' repeatedly until it has found the file it is looking for or until the server responds with a message indicating an error or end of file. The client should then close the handle using the 'close' request. Note: directory entries "." and ".." are NOT included into readdir() response.
Reply:
R • <token> • <array of directory entries> • <error report> • <boolean: eof> •
<array of directory entries>
⇒ null
⇒ [ ]
⇒ [ <directory entry list> ]
<directory entry list>
⇒ <directory entry>
⇒ <directory entry list> , <directory entry>
<directory entry>
⇒ <object>
Directory entry attributes are:
"FileName" : <string>
- a file name being returned, it will be a relative name within the directory,
without any path components.
"LongName" : <string>
- a human readable, expanded format for the file name, similar to what
is returned by "ls -l" on Unix systems
"Attrs" : <file attributes>
- the attributes of the file as described in Section File Attributes.
C • <token> • FileSystem • mkdir • <string: directory path> • <file attributes> •
The command creates a directory on the server. <string: directory path> specifies the directory to be created. <file attributes> specifies new directory attributes.
Reply:
R • <token> • <error report> •
C • <token> • FileSystem • rmdir • <string: directory path> •
The command removes a directory. An error will be returned if no directory with the specified path exists, or if the specified directory is not empty, or if the path specified a file system object other than a directory. <string: directory path> - specifies the directory to be removed.
Reply:
R • <token> • <error report> •
C • <token> • FileSystem • roots •
The command retrieves file system roots - top level file system objects. UNIX file system can report just one root with path "/". Other types of systems can have more the one root. For example, Windows server can return multiple roots: one per disc (e.g. "/C:/", "/D:/", etc.). Note: even Windows implementation of the service must use forward slash as directory separator, and must start absolute path with "/". Server should implement proper translation of protocol file names to OS native names and back.
Reply:
R • <token> • <array of directory entries> • <error report> •
C • <token> • FileSystem • remove • <string: path> •
The command removes a file or symbolic link. This request cannot be used to remove directories.
Reply:
R • <token> • <error report> •
C • <token> • FileSystem • realpath • <string: path> •
The command canonicalizes any given path name to an absolute path. This is useful for converting path names containing ".." components or relative pathnames without a leading slash into absolute paths.
Reply:
R • <token> • <error report> • <string: path> •
C • <token> • FileSystem • rename • <string: old path> • <string: new path> •
The command renames a file. It is an error if there already exists a file with the name specified by <string: new path>. The server may also fail rename requests in other situations, for example if <string: old path> and <string: new path> point to different file systems on the server.
Reply:
R • <token> • <error report> •
C • <token> • FileSystem • readlink • <string: link path> •
The command reads the target of a symbolic link. <string: link path> specifies the path name of the symbolic link to be read.
Reply:
R • <token> • <error report> • <string: path> •
C • <token> • FileSystem • symlink • <string: link path> • <string: target path> •
The command creates a symbolic link on the server. <string: link path> specifies the path name of the symbolic link to be created. <string: target path> specifies the target of the symbolic link.
Reply:
R • <token> • <error report> •
C • <token> • FileSystem • copy • <string: source path> • <string: destination path> •
<boolean: copy permissions> • <boolean: copy ownership> •
The command copies a file on remote system. <string: source path> specifies the path name of the file to be copied. <string: destination path> specifies destination file name. If <boolean: copy permissions> is true then copy source file permissions. If <boolean: copy ownership> is true then copy source file UID and GID.
Reply:
R • <token> • <error report> •
C • <token> • FileSystem • user •
The command retrieves information about user account, which is used by server to access file system on behalf of the client.
Reply:
R • <token> • <int: real UID> • <int: effective UID> •
<int: real GID> • <int: effective GID> • <string: home directory> •
/**
* File System service provides file transfer (and more generally file
* system access) functionality in TCF. The service design is
* derived from SSH File Transfer Protocol specifications.
*
* Request Synchronization and Reordering
*
* The protocol and implementations MUST process requests relating to
* the same file in the order in which they are received. In other
* words, if an application submits multiple requests to the server, the
* results in the responses will be the same as if it had sent the
* requests one at a time and waited for the response in each case. For
* example, the server may process non-overlapping read/write requests
* to the same file in parallel, but overlapping reads and writes cannot
* be reordered or parallelized. However, there are no ordering
* restrictions on the server for processing requests from two different
* file transfer connections. The server may interleave and parallelize
* them at will.
*
* There are no restrictions on the order in which responses to
* outstanding requests are delivered to the client, except that the
* server must ensure fairness in the sense that processing of no
* request will be indefinitely delayed even if the client is sending
* other requests so that there are multiple outstanding requests all
* the time.
*
* There is no limit on the number of outstanding (non-acknowledged)
* requests that the client may send to the server. In practice this is
* limited by the buffering available on the data stream and the queuing
* performed by the server. If the server's queues are full, it should
* not read any more data from the stream, and flow control will prevent
* the client from sending more requests.
*
* File Names
*
* This protocol represents file names as strings. File names are
* assumed to use the slash ('/') character as a directory separator.
*
* File names starting with a slash are "absolute", and are relative to
* the root of the file system. Names starting with any other character
* are relative to the user's default directory (home directory). Client
* can use 'user()' command to retrieve current user home directory.
*
* Servers SHOULD interpret a path name component ".." as referring to
* the parent directory, and "." as referring to the current directory.
* If the server implementation limits access to certain parts of the
* file system, it must be extra careful in parsing file names when
* enforcing such restrictions. There have been numerous reported
* security bugs where a ".." in a path name has allowed access outside
* the intended area.
*
* An empty path name is valid, and it refers to the user's default
* directory (usually the user's home directory).
*
* Otherwise, no syntax is defined for file names by this specification.
* Clients should not make any other assumptions; however, they can
* splice path name components returned by readdir() together
* using a slash ('/') as the separator, and that will work as expected.
*
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface IFileSystem extends IService {
/**
* This service name, as it appears on the wire - a TCF name of the service.
*/
static final String NAME = "FileSystem";
/**
* Flags to be used with open() method.
*/
static final int
/**
* Open the file for reading.
*/
TCF_O_READ = 0x00000001,
/**
* Open the file for writing. If both this and TCF_O_READ are
* specified, the file is opened for both reading and writing.
*/
TCF_O_WRITE = 0x00000002,
/**
* Force all writes to append data at the end of the file.
*/
TCF_O_APPEND = 0x00000004,
/**
* If this flag is specified, then a new file will be created if one
* does not already exist (if TCF_O_TRUNC is specified, the new file will
* be truncated to zero length if it previously exists).
*/
TCF_O_CREAT = 0x00000008,
/**
* Forces an existing file with the same name to be truncated to zero
* length when creating a file by specifying TCF_O_CREAT.
* TCF_O_CREAT MUST also be specified if this flag is used.
*/
TCF_O_TRUNC = 0x00000010,
/**
* Causes the request to fail if the named file already exists.
* TCF_O_CREAT MUST also be specified if this flag is used.
*/
TCF_O_EXCL = 0x00000020;
/**
* Flags to be used together with FileAttrs.
* The flags specify which of the fields are present. Those fields
* for which the corresponding flag is not set are not present (not
* included in the message).
*/
static final int
ATTR_SIZE = 0x00000001,
ATTR_UIDGID = 0x00000002,
ATTR_PERMISSIONS = 0x00000004,
ATTR_ACMODTIME = 0x00000008;
/**
* FileAttrs is used both when returning file attributes from
* the server and when sending file attributes to the server. When
* sending it to the server, the flags field specifies which attributes
* are included, and the server will use default values for the
* remaining attributes (or will not modify the values of remaining
* attributes). When receiving attributes from the server, the flags
* specify which attributes are included in the returned data. The
* server normally returns all attributes it knows about.
*/
final static class FileAttrs {
/**
* The `flags' specify which of the fields are present.
*/
public final int flags;
/**
* The `size' field specifies the size of the file in bytes.
*/
public final long size;
/**
* The `uid' and `gid' fields contain numeric Unix-like user and group
* identifiers, respectively.
*/
public final int uid;
public final int gid;
/**
* The `permissions' field contains a bit mask of file permissions as
* defined by posix [1].
*/
public final int permissions;
/**
* The `atime' and `mtime' contain the access and modification times of
* the files, respectively. They are represented as milliseconds from
* midnight Jan 1, 1970 in UTC.
*/
public final long atime;
public final long mtime;
/**
* Additional (non-standard) attributes.
*/
public final Map<String,Object> attributes;
public FileAttrs(int flags, long size, int uid, int gid,
int permissions, long atime, long mtime, Map<String,Object> attributes) {
this.flags = flags;
this.size = size;
this.uid = uid;
this.gid = gid;
this.permissions = permissions;
this.atime = atime;
this.mtime = mtime;
this.attributes = attributes;
}
/**
* Determines if the file system object is a file on the remote file system.
*
* @return true if and only if the object on the remote system can be considered to have "contents" that
* have the potential to be read and written as a byte stream.
*/
public boolean isFile() {
if ((flags & ATTR_PERMISSIONS) == 0) return false;
return (permissions & S_IFMT) == S_IFREG;
}
/**
* Determines if the file system object is a directory on the remote file system.
*
* @return true if and only if the object on the remote system is a directory.
* That is, it contains entries that can be interpreted as other files.
*/
public boolean isDirectory() {
if ((flags & ATTR_PERMISSIONS) == 0) return false;
return (permissions & S_IFMT) == S_IFDIR;
}
}
/**
* The following flags are defined for the 'permissions' field:
*/
static final int
S_IFMT = 0170000, // bitmask for the file type bitfields
S_IFSOCK = 0140000, // socket
S_IFLNK = 0120000, // symbolic link
S_IFREG = 0100000, // regular file
S_IFBLK = 0060000, // block device
S_IFDIR = 0040000, // directory
S_IFCHR = 0020000, // character device
S_IFIFO = 0010000, // fifo
S_ISUID = 0004000, // set UID bit
S_ISGID = 0002000, // set GID bit (see below)
S_ISVTX = 0001000, // sticky bit (see below)
S_IRWXU = 00700, // mask for file owner permissions
S_IRUSR = 00400, // owner has read permission
S_IWUSR = 00200, // owner has write permission
S_IXUSR = 00100, // owner has execute permission
S_IRWXG = 00070, // mask for group permissions
S_IRGRP = 00040, // group has read permission
S_IWGRP = 00020, // group has write permission
S_IXGRP = 00010, // group has execute permission
S_IRWXO = 00007, // mask for permissions for others (not in group)
S_IROTH = 00004, // others have read permission
S_IWOTH = 00002, // others have write permission
S_IXOTH = 00001; // others have execute permission
final static class DirEntry {
/**
* `filename' is a file name being returned. It is a relative name within
* the directory, without any path components;
*/
public final String filename;
/**
* `longname' is an expanded format for the file name, similar to what
* is returned by "ls -l" on Unix systems.
* The format of the `longname' field is unspecified by this protocol.
* It MUST be suitable for use in the output of a directory listing
* command (in fact, the recommended operation for a directory listing
* command is to simply display this data). However, clients SHOULD NOT
* attempt to parse the longname field for file attributes; they SHOULD
* use the attrs field instead.
*/
public final String longname;
/**
* `attrs' is the attributes of the file.
*/
public final FileAttrs attrs;
public DirEntry(String filename, String longname, FileAttrs attrs) {
this.filename = filename;
this.longname = longname;
this.attrs = attrs;
}
}
/**
* Opaque representation of open file handle.
* Note: open file handle can be used only with service instance that
* created the handle.
*/
interface IFileHandle {
IFileSystem getService();
}
/**
* Service specific error codes.
*/
static final int
/**
* Indicates end-of-file condition; for read() it means that no
* more data is available in the file, and for readdir() it
* indicates that no more files are contained in the directory.
*/
STATUS_EOF = 0x10001,
/**
* This code is returned when a reference is made to a file which
* should exist but doesn't.
*/
STATUS_NO_SUCH_FILE = 0x10002,
/**
* is returned when the authenticated user does not have sufficient
* permissions to perform the operation.
*/
STATUS_PERMISSION_DENIED = 0x10003;
/**
* The class to represent File System error reports.
*/
@SuppressWarnings("serial")
abstract static class FileSystemException extends IOException {
protected FileSystemException(String message) {
super(message);
}
protected FileSystemException(Exception x) {
super(x.getMessage());
initCause(x);
}
/**
* Get error code. The code can be standard TCF error code or
* one of service specific codes, see STATUS_*.
* @return error code.
*/
public abstract int getStatus();
}
/**
* Open or create a file on a remote system.
*
* @param file_name specifies the file name. See 'File Names' for more information.
* @param flags is a bit mask of TCF_O_* flags.
* @param attrs specifies the initial attributes for the file.
* Default values will be used for those attributes that are not specified.
* @param done is call back object.
* @return pending command handle.
*/
IToken open(String file_name, int flags, FileAttrs attrs, DoneOpen done);
interface DoneOpen {
void doneOpen(IToken token, FileSystemException error, IFileHandle handle);
}
/**
* Close a file on a remote system.
*
* @param handle is a handle previously returned in the response to
* open() or opendir().
* @param done is call back object.
* @return pending command handle.
*/
IToken close(IFileHandle handle, DoneClose done);
interface DoneClose {
void doneClose(IToken token, FileSystemException error);
}
/**
* Read bytes from an open file.
* In response to this request, the server will read as many bytes as it
* can from the file (up to `len'), and return them in a byte array.
* If an error occurs or EOF is encountered, the server may return
* fewer bytes then requested. Call back method doneRead() argument 'error'
* will be not null in case of error, and argument 'eof' will be
* true in case of EOF. For normal disk files, it is guaranteed
* that this will read the specified number of bytes, or up to end of file
* or error. For e.g. device files this may return fewer bytes than requested.
*
* @param handle is an open file handle returned by open().
* @param offset is the offset (in bytes) relative
* to the beginning of the file from where to start reading.
* If offset < 0 then reading starts from current position in the file.
* @param len is the maximum number of bytes to read.
* @param done is call back object.
* @return pending command handle.
*/
IToken read(IFileHandle handle, long offset, int len, DoneRead done);
interface DoneRead {
void doneRead(IToken token, FileSystemException error, byte[] data, boolean eof);
}
/**
* Write bytes into an open file.
* The write will extend the file if writing beyond the end of the file.
* It is legal to write way beyond the end of the file; the semantics
* are to write zeroes from the end of the file to the specified offset
* and then the data.
*
* @param handle is an open file handle returned by open().
* @param offset is the offset (in bytes) relative
* to the beginning of the file from where to start writing.
* If offset < 0 then writing starts from current position in the file.
* @param data is byte array that contains data for writing.
* @param data_pos if offset in 'data' of first byte to write.
* @param data_size is the number of bytes to write.
* @param done is call back object.
* @return pending command handle.
*/
IToken write(IFileHandle handle, long offset,
byte[] data, int data_pos, int data_size, DoneWrite done);
interface DoneWrite {
void doneWrite(IToken token, FileSystemException error);
}
/**
* Retrieve file attributes.
*
* @param path - specifies the file system object for which
* status is to be returned.
* @param done is call back object.
* @return pending command handle.
*/
IToken stat(String path, DoneStat done);
/**
* Retrieve file attributes.
* Unlike 'stat()', 'lstat()' does not follow symbolic links.
*
* @param path - specifies the file system object for which
* status is to be returned.
* @param done is call back object.
* @return pending command handle.
*/
IToken lstat(String path, DoneStat done);
/**
* Retrieve file attributes for an open file (identified by the file handle).
*
* @param handle is a file handle returned by 'open()'.
* @param done is call back object.
* @return pending command handle.
*/
IToken fstat(IFileHandle handle, DoneStat done);
interface DoneStat {
void doneStat(IToken token, FileSystemException error, FileAttrs attrs);
}
/**
* Set file attributes.
* This request is used for operations such as changing the ownership,
* permissions or access times, as well as for truncating a file.
* An error will be returned if the specified file system object does
* not exist or the user does not have sufficient rights to modify the
* specified attributes.
*
* @param path specifies the file system object (e.g. file or directory)
* whose attributes are to be modified.
* @param attrs specifies the modifications to be made to file attributes.
* @param done is call back object.
* @return pending command handle.
*/
IToken setstat(String path, FileAttrs attrs, DoneSetStat done);
/**
* Set file attributes for an open file (identified by the file handle).
* This request is used for operations such as changing the ownership,
* permissions or access times, as well as for truncating a file.
*
* @param handle is a file handle returned by 'open()'.
* @param attrs specifies the modifications to be made to file attributes.
* @param done is call back object.
* @return pending command handle.
*/
IToken fsetstat(IFileHandle handle, FileAttrs attrs, DoneSetStat done);
interface DoneSetStat {
void doneSetStat(IToken token, FileSystemException error);
}
/**
* The opendir() command opens a directory for reading.
* Once the directory has been successfully opened, files (and
* directories) contained in it can be listed using readdir() requests.
* When the client no longer wishes to read more names from the
* directory, it SHOULD call close() for the handle. The handle
* should be closed regardless of whether an error has occurred or not.
* @param path - name of the directory to be listed (without any trailing slash).
* @param done - result call back object.
* @return pending command handle.
*/
IToken opendir(String path, DoneOpen done);
/**
* The files in a directory can be listed using the opendir() and
* readdir() requests. Each readdir() request returns one
* or more file names with full file attributes for each file. The
* client should call readdir() repeatedly until it has found the
* file it is looking for or until the server responds with a
* message indicating an error or end of file. The client should then
* close the handle using the close() request.
* Note: directory entries "." and ".." are NOT included into readdir()
* response.
* @param handle - file handle created by opendir()
* @param done - result call back object.
* @return pending command handle.
*/
IToken readdir(IFileHandle handle, DoneReadDir done);
interface DoneReadDir {
void doneReadDir(IToken token, FileSystemException error, DirEntry[] entries, boolean eof);
}
/**
* Create a directory on the server.
*
* @param path - specifies the directory to be created.
* @param attrs - new directory attributes.
* @param done - result call back object.
* @return pending command handle.
*/
IToken mkdir(String path, FileAttrs attrs, DoneMkDir done);
interface DoneMkDir {
void doneMkDir(IToken token, FileSystemException error);
}
/**
* Remove a directory.
* An error will be returned if no directory
* with the specified path exists, or if the specified directory is not
* empty, or if the path specified a file system object other than a
* directory.
*
* @param path - specifies the directory to be removed.
* @param done - result call back object.
* @return pending command handle.
*/
IToken rmdir(String path, DoneRemove done);
interface DoneRemove {
void doneRemove(IToken token, FileSystemException error);
}
/**
* Retrieve file system roots - top level file system objects.
* UNIX file system can report just one root with path "/". Other types of systems
* can have more the one root. For example, Windows server can return multiple roots:
* one per disc (e.g. "/C:/", "/D:/", etc.). Note: even Windows implementation of
* the service must use forward slash as directory separator, and must start
* absolute path with "/". Server should implement proper translation of
* protocol file names to OS native names and back.
*
* @param done - result call back object.
* @return pending command handle.
*/
IToken roots(DoneRoots done);
interface DoneRoots {
void doneRoots(IToken token, FileSystemException error, DirEntry[] entries);
}
/**
* Remove a file or symbolic link.
* This request cannot be used to remove directories.
*
* @param file_name is the name of the file to be removed.
* @param done - result call back object.
* @return pending command handle.
*/
IToken remove(String file_name, DoneRemove done);
/**
* Canonicalize any given path name to an absolute path.
* This is useful for converting path names containing ".." components or
* relative pathnames without a leading slash into absolute paths.
*
* @param path specifies the path name to be canonicalized.
* @param done - result call back object.
* @return pending command handle.
*/
IToken realpath(String path, DoneRealPath done);
interface DoneRealPath {
void doneRealPath(IToken token, FileSystemException error, String path);
}
/**
* Rename a file.
* It is an error if there already exists a file
* with the name specified by 'new_path'. The server may also fail rename
* requests in other situations, for example if `old_path' and `new_path'
* point to different file systems on the server.
*
* @param old_path is the name of an existing file or directory.
* @param new_path is the new name for the file or directory.
* @param done - result call back object.
* @return pending command handle.
*/
IToken rename(String old_path, String new_path, DoneRename done);
interface DoneRename {
void doneRename(IToken token, FileSystemException error);
}
/**
* Read the target of a symbolic link.
*
* @param path specifies the path name of the symbolic link to be read.
* @param done - result call back object.
* @return pending command handle.
*/
IToken readlink(String path, DoneReadLink done);
interface DoneReadLink {
void doneReadLink(IToken token, FileSystemException error, String path);
}
/**
* Create a symbolic link on the server.
*
* @param link_path specifies the path name of the symbolic link to be created.
* @param target_path specifies the target of the symbolic link.
* @param done - result call back object.
* @return pending command handle.
*/
IToken symlink(String link_path, String target_path, DoneSymLink done);
interface DoneSymLink {
void doneSymLink(IToken token, FileSystemException error);
}
/**
* Copy a file on remote system.
*
* @param src_path specifies the path name of the file to be copied.
* @param dst_path specifies destination file name.
* @param copy_permissions - if true then copy source file permissions.
* @param copy_ownership - if true then copy source file UID and GID.
* @param done - result call back object.
* @return pending command handle.
*/
IToken copy(String src_path, String dst_path,
boolean copy_permissions, boolean copy_ownership, DoneCopy done);
interface DoneCopy {
void doneCopy(IToken token, FileSystemException error);
}
/**
* Retrieve information about user account, which is used by server
* to access file system on behalf of the client.
*
* @param done - result call back object.
* @return pending command handle.
*/
IToken user(DoneUser done);
interface DoneUser {
void doneUser(IToken token, FileSystemException error,
int real_uid, int effective_uid, int real_gid, int effective_gid,
String home);
}
}