| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| <html> |
| <head> |
| <title>Target Communication Framework Services - File System</title> |
| </head> |
| |
| <body lang='EN-US'> |
| |
| <h1>Target Communication Framework Services - File System</h1> |
| |
| <ul> |
| <li><a href='#VersionHistory'>Version History</a> |
| <li><a href='#Overview'>Overview</a> |
| <li><a href='#ReqSync'>Request Synchronization and Reordering</a> |
| <li><a href='#FileNames'>File Names</a> |
| <li><a href='#FileModes'>File Open Modes</a> |
| <li><a href='#FileAttributes'>File Attributes</a> |
| <li><a href='#ErrorCodes'>Error Codes</a> |
| <li><a href='#Cmds'>Commands</a> |
| <ul> |
| <li><a href='#CmdOpen'>open</a> |
| <li><a href='#CmdClose'>close</a> |
| <li><a href='#CmdRead'>read</a> |
| <li><a href='#CmdWrite'>write</a> |
| <li><a href='#CmdStat'>stat</a> |
| <li><a href='#CmdLStat'>lstat</a> |
| <li><a href='#CmdFStat'>fstat</a> |
| <li><a href='#CmdSetStat'>setstat</a> |
| <li><a href='#CmdFSetStat'>fsetstat</a> |
| <li><a href='#CmdOpenDir'>opendir</a> |
| <li><a href='#CmdReadDir'>readdir</a> |
| <li><a href='#CmdMkDir'>mkdir</a> |
| <li><a href='#CmdRmDir'>rmdir</a> |
| <li><a href='#CmdRoots'>roots</a> |
| <li><a href='#CmdRemove'>remove</a> |
| <li><a href='#CmdRealPath'>realpath</a> |
| <li><a href='#CmdRename'>rename</a> |
| <li><a href='#CmdReadLink'>readlink</a> |
| <li><a href='#CmdSymLink'>symlink</a> |
| <li><a href='#CmdSymLink'>copy</a> |
| <li><a href='#CmdSymLink'>user</a> |
| </ul> |
| <li><a href='#API'>API</a> |
| </ul> |
| |
| <h1>File System Service</h1> |
| |
| <h2><a name='VersionHistory'>Version History</a></h2> |
| |
| <table border=1 cellpadding=8> |
| <tr> |
| <th>Version |
| <th>Date |
| <th>Change |
| <tr> |
| <td>0.1 |
| <td>2008-01-10 |
| <td>Initial contribution |
| </table> |
| |
| <h2><a name='Overview'>Overview</a></h2> |
| |
| <p>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.</p> |
| |
| <h2><a name='ReqSync'>Request Synchronization and Reordering</a></h2> |
| |
| <p>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.</p> |
| |
| <p>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.</p> |
| |
| <p>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.</p> |
| |
| <h2><a name='FileNames'>File Names</a></h2> |
| |
| <p>This protocol represents file names as strings. File names are |
| assumed to use the slash ('/') character as a directory separator.</p> |
| |
| <p>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.</p> |
| |
| <p>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.</p> |
| |
| <p>An empty path name is valid, and it refers to the user's default |
| directory (usually the user's home directory).</p> |
| |
| <p>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.</p> |
| |
| <h2><a name='FileModes'>File Open Modes</a></h2> |
| |
| <p>File open mode is bitwise OR of mode flags:</p> |
| |
| <dl> |
| <dt><code>TCF_O_READ = 0x00000001</code> |
| <dd>Open the file for reading. |
| |
| <dt><code>TCF_O_WRITE = 0x00000002</code> |
| <dd>Open the file for writing. If both this and TCF_O_READ are |
| specified, the file is opened for both reading and writing. |
| |
| <dt><code>TCF_O_APPEND = 0x00000004</code> |
| <dd>Force all writes to append data at the end of the file. |
| |
| <dt><code>TCF_O_CREAT = 0x00000008</code> |
| <dd>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). |
| |
| <dt><code>TCF_O_TRUNC = 0x00000010</code> |
| <dd>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. |
| |
| <dt><code>TCF_O_EXCL = 0x00000020</code> |
| <dd>Causes the request to fail if the named file already exists. |
| TCF_O_CREAT MUST also be specified if this flag is used. |
| </dl> |
| |
| <h2><a name='FileAttributes'>File Attributes</a></h2> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| <i><file attributes></i> |
| ⇒ <i><object></i> |
| </font></b></pre> |
| |
| <p>All attributes are optional. |
| Tools and targets can define additional attributes. Predefined attributes are:</p> |
| <ul> |
| <li><code><b><font face="Courier New" size=2 color=#333399>"Size" : <i><int></i></font></b></code> |
| - file size in bytes |
| <li><code><b><font face="Courier New" size=2 color=#333399>"UID" : <i><int></i></font></b></code> |
| - file owner user ID |
| <li><code><b><font face="Courier New" size=2 color=#333399>"GID" : <i><int></i></font></b></code> |
| - file owner group ID |
| <li><code><b><font face="Courier New" size=2 color=#333399>"Permissions" : <i><int></i></font></b></code> |
| - file access permissions |
| <li><code><b><font face="Courier New" size=2 color=#333399>"ATime" : <i><int></i></font></b></code> |
| - file last access time |
| <li><code><b><font face="Courier New" size=2 color=#333399>"MTime" : <i><int></i></font></b></code> |
| - file last modification time |
| </ul> |
| |
| <h2><a name='ErrorCodes'>Error codes</a></h2> |
| |
| <p>The service uses standard format for error reports, |
| see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p> |
| |
| <p>Currently, the following values are defined for service specific error codes (other values may be |
| defined by future versions of this protocol):</p> |
| |
| <dl> |
| <dt><code>STATUS_EOF = 0x10001</code> |
| <dd>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. |
| |
| <dt><code>STATUS_NO_SUCH_FILE = 0x10002</code> |
| <dd>This code is returned when a reference is made to a file which |
| should exist but doesn't. |
| |
| <dt><code>STATUS_PERMISSION_DENIED = 0x10003</code> |
| <dd>is returned when the authenticated user does not have sufficient |
| permissions to perform the operation. |
| </dl> |
| |
| <h2><a name='Cmds'>Commands</a></h2> |
| |
| <h3><a name='CmdOpen'>open</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • FileSystem • open • <i><string: file name></i> • <i><int: mode></i> • <i><file attributes></i> • |
| </font></b></pre> |
| |
| <p>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.</p> |
| |
| <p>Reply:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><error report></i> • <i><file handle></i> • |
| |
| <i><file handle></i> |
| ⇒ null |
| ⇒ <i><string></i> |
| </font></b></pre> |
| |
| <p>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.</p> |
| |
| <h3><a name='CmdClose'>close</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • FileSystem • close • <i><string: file handle></i> • |
| </font></b></pre> |
| |
| <p>The command closes a handle, which was open by 'open' or 'opendir' commands.</p> |
| |
| <p>Reply:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><error report></i> • |
| </font></b></pre> |
| |
| <h3><a name='CmdRead'>read</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • FileSystem • read • <i><string: file handle></i> • <i><int: offset></i> • <i><int: size></i> • |
| </font></b></pre> |
| |
| <p>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.</p> |
| |
| <p>If 'offset' < 0 then reading will start from current position in the file.</p> |
| |
| <p>Reply:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><string: data></i> • <i><error report></i> • <i><boolean: eof></i> • |
| </font></b></pre> |
| |
| <p><i><string: data></i> 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.</p> |
| |
| <h3><a name='CmdWrite'>write</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • FileSystem • write • <i><string: file handle></i> • <i><int: offset></i> • <i><string: data></i> • |
| </font></b></pre> |
| |
| <p>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. <i><string: data></i> is Base64 encoded array of data bytes.</p> |
| |
| <p>If 'offset' < 0 then writing will start from current position in the file.</p> |
| |
| <p>Reply:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><error report></i> • |
| </font></b></pre> |
| |
| <h3><a name='CmdStat'>stat</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • FileSystem • stat • <i><string: file name></i> • |
| </font></b></pre> |
| |
| <p>The command retrieves file attributes.</p> |
| |
| <p>Reply:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><error report></i> • <i><file attributes></i> • |
| </font></b></pre> |
| |
| <h3><a name='CmdLStat'>lstat</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • FileSystem • lstat • <i><string: file name></i> • |
| </font></b></pre> |
| |
| <p>The command retrieves file attributes. |
| Unlike 'stat', 'lstat' does not follow symbolic links.</p> |
| |
| <p>Reply:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><error report></i> • <i><file attributes></i> • |
| </font></b></pre> |
| |
| <h3><a name='CmdFStat'>fstat</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • FileSystem • fstat • <i><string: file handle></i> • |
| </font></b></pre> |
| |
| <p>The command retrieves file attributes for an open file (identified by the file handle).</p> |
| |
| <p>Reply:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><error report></i> • <i><file attributes></i> • |
| </font></b></pre> |
| |
| <h3><a name='CmdSetStat'>setstat</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • FileSystem • setstat • <i><string: file name></i> • <i><file attributes></i> • |
| </font></b></pre> |
| |
| <p>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.</p> |
| |
| <p>Reply:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><error report></i> • |
| </font></b></pre> |
| |
| <h3><a name='CmdFSetStat'>fsetstat</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • FileSystem • fsetstat • <i><string: file handle></i> • <i><file attributes></i> • |
| </font></b></pre> |
| |
| <p>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.</p> |
| |
| <p>Reply:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><error report></i> • |
| </font></b></pre> |
| |
| <h3><a name='CmdOpenDir'>opendir</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • FileSystem • opendir • <i><string: path></i> • |
| </font></b></pre> |
| |
| <p>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.</p> |
| |
| <p>Reply:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><error report></i> • <i><file handle></i> • |
| </font></b></pre> |
| |
| <h3><a name='CmdReadDir'>readdir</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • FileSystem • readdir • <i><string: file handle></i> • |
| </font></b></pre> |
| |
| <p>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.</p> |
| |
| <p>Reply:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><array of directory entries></i> • <i><error report></i> • <i><boolean: eof></i> • |
| |
| <i><array of directory entries></i> |
| ⇒ null |
| ⇒ [ ] |
| ⇒ [ <i><directory entry list></i> ] |
| |
| <i><directory entry list></i> |
| ⇒ <i><directory entry></i> |
| ⇒ <i><directory entry list></i> , <i><directory entry></i> |
| |
| <i><directory entry></i> |
| ⇒ <i><object></i> |
| </font></b></pre> |
| |
| <p>Directory entry attributes are:</p> |
| <ul> |
| <li><code><b><font face="Courier New" size=2 color=#333399>"FileName" : <i><string></i></font></b></code> |
| - a file name being returned, it will be a relative name within the directory, |
| without any path components. |
| <li><code><b><font face="Courier New" size=2 color=#333399>"LongName" : <i><string></i></font></b></code> |
| - a human readable, expanded format for the file name, similar to what |
| is returned by "ls -l" on Unix systems |
| <li><code><b><font face="Courier New" size=2 color=#333399>"Attrs" : <i><file attributes></i></font></b></code> |
| - the attributes of the file as described in Section <a href='#FileAttributes'>File Attributes</a>. |
| </ul> |
| |
| <h3><a name='CmdMkDir'>mkdir</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • FileSystem • mkdir • <i><string: directory path></i> • <i><file attributes></i> • |
| </font></b></pre> |
| |
| <p>The command creates a directory on the server. |
| <i><string: directory path></i> specifies the directory to be created. |
| <i><file attributes></i> specifies new directory attributes.</p> |
| |
| <p>Reply:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><error report></i> • |
| </font></b></pre> |
| |
| <h3><a name='CmdRmDir'>rmdir</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • FileSystem • rmdir • <i><string: directory path></i> • |
| </font></b></pre> |
| |
| <p>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. <i><string: directory path></i> - specifies the directory to be removed.</p> |
| |
| <p>Reply:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><error report></i> • |
| </font></b></pre> |
| |
| <h3><a name='CmdRoots'>roots</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • FileSystem • roots • |
| </font></b></pre> |
| |
| <p>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.</p> |
| |
| <p>Reply:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><array of directory entries></i> • <i><error report></i> • |
| </font></b></pre> |
| |
| <h3><a name='CmdRemove'>remove</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • FileSystem • remove • <i><string: path></i> • |
| </font></b></pre> |
| |
| <p>The command removes a file or symbolic link. |
| This request cannot be used to remove directories.</p> |
| |
| <p>Reply:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><error report></i> • |
| </font></b></pre> |
| |
| <h3><a name='CmdRealPath'>realpath</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • FileSystem • realpath • <i><string: path></i> • |
| </font></b></pre> |
| |
| <p>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.</p> |
| |
| <p>Reply:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><error report></i> • <i><string: path></i> • |
| </font></b></pre> |
| |
| <h3><a name='CmdRename'>rename</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • FileSystem • rename • <i><string: old path></i> • <i><string: new path></i> • |
| </font></b></pre> |
| |
| <p>The command renames a file. |
| It is an error if there already exists a file |
| with the name specified by <i><string: new path></i>. The server may also fail rename |
| requests in other situations, for example if <i><string: old path></i> and <i><string: new path></i> |
| point to different file systems on the server.</p> |
| |
| <p>Reply:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><error report></i> • |
| </font></b></pre> |
| |
| <h3><a name='CmdReadLink'>readlink</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • FileSystem • readlink • <i><string: link path></i> • |
| </font></b></pre> |
| |
| <p>The command reads the target of a symbolic link. |
| <i><string: link path></i> specifies the path name of the symbolic link to be read.</p> |
| |
| <p>Reply:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><error report></i> • <i><string: path></i> • |
| </font></b></pre> |
| |
| <h3><a name='CmdSymLink'>symlink</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • FileSystem • symlink • <i><string: link path></i> • <i><string: target path></i> • |
| </font></b></pre> |
| |
| <p>The command creates a symbolic link on the server. |
| <i><string: link path></i> specifies the path name of the symbolic link to be created. |
| <i><string: target path></i> specifies the target of the symbolic link.</p> |
| |
| <p>Reply:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><error report></i> • |
| </font></b></pre> |
| |
| <h3><a name='CmdCopy'>copy</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • FileSystem • copy • <i><string: source path></i> • <i><string: destination path></i> • |
| <i><boolean: copy permissions></i> • <i><boolean: copy ownership></i> • |
| </font></b></pre> |
| |
| <p>The command copies a file on remote system. |
| <i><string: source path></i> specifies the path name of the file to be copied. |
| <i><string: destination path></i> specifies destination file name. |
| If <i><boolean: copy permissions></i> is true then copy source file permissions. |
| If <i><boolean: copy ownership></i> is true then copy source file UID and GID.</p> |
| |
| <p>Reply:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><error report></i> • |
| </font></b></pre> |
| |
| <h3><a name='CmdUser'>user</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • FileSystem • user • |
| </font></b></pre> |
| |
| <p>The command retrieves information about user account, which is used by server |
| to access file system on behalf of the client.</p> |
| |
| <p>Reply:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><int: real UID></i> • <i><int: effective UID></i> • |
| <i><int: real GID></i> • <i><int: effective GID></i> • <i><string: home directory></i> • |
| </font></b></pre> |
| |
| <h2><a name='API'>API</a></h2> |
| |
| <pre> |
| <font color=#3F5FBF>/** |
| * 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. |
| */</font> |
| <font color=#7F0055>public interface</font> IFileSystem <font color=#7F0055>extends</font> IService { |
| |
| <font color=#3F5FBF>/** |
| * Service name. |
| */</font> |
| <font color=#7F0055>static final</font> String NAME = "FileSystem"; |
| |
| <font color=#3F5FBF>/** |
| * Flags to be used with open() method. |
| */</font> |
| <font color=#7F0055>static final int</font> |
| |
| <font color=#3F5FBF>/** |
| * Open the file for reading. |
| */</font> |
| TCF_O_READ = 0x00000001, |
| |
| <font color=#3F5FBF>/** |
| * Open the file for writing. If both this and TCF_O_READ are |
| * specified, the file is opened for both reading and writing. |
| */</font> |
| TCF_O_WRITE = 0x00000002, |
| |
| <font color=#3F5FBF>/** |
| * Force all writes to append data at the end of the file. |
| */</font> |
| TCF_O_APPEND = 0x00000004, |
| |
| <font color=#3F5FBF>/** |
| * 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). |
| */</font> |
| TCF_O_CREAT = 0x00000008, |
| |
| <font color=#3F5FBF>/** |
| * 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. |
| */</font> |
| TCF_O_TRUNC = 0x00000010, |
| |
| <font color=#3F5FBF>/** |
| * Causes the request to fail if the named file already exists. |
| * TCF_O_CREAT MUST also be specified if this flag is used. |
| */</font> |
| TCF_O_EXCL = 0x00000020; |
| |
| <font color=#3F5FBF>/** |
| * 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). |
| */</font> |
| <font color=#7F0055>static final int</font> |
| ATTR_SIZE = 0x00000001, |
| ATTR_UIDGID = 0x00000002, |
| ATTR_PERMISSIONS = 0x00000004, |
| ATTR_ACMODTIME = 0x00000008; |
| |
| <font color=#3F5FBF>/** |
| * 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. |
| */</font> |
| <font color=#7F0055>final static class</font> FileAttrs { |
| |
| <font color=#3F5FBF>/** |
| * The `flags' specify which of the fields are present. |
| */</font> |
| <font color=#7F0055>public final int</font> flags; |
| |
| <font color=#3F5FBF>/** |
| * The `size' field specifies the size of the file in bytes. |
| */</font> |
| <font color=#7F0055>public final long</font> size; |
| |
| <font color=#3F5FBF>/** |
| * The `uid' and `gid' fields contain numeric Unix-like user and group |
| * identifiers, respectively. |
| */</font> |
| <font color=#7F0055>public final int</font> uid; |
| <font color=#7F0055>public final int</font> gid; |
| |
| <font color=#3F5FBF>/** |
| * The `permissions' field contains a bit mask of file permissions as |
| * defined by posix [1]. |
| */</font> |
| <font color=#7F0055>public final int</font> permissions; |
| |
| <font color=#3F5FBF>/** |
| * 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. |
| */</font> |
| <font color=#7F0055>public final long</font> atime; |
| <font color=#7F0055>public final long</font> mtime; |
| |
| <font color=#3F5FBF>/** |
| * Additional (non-standard) attributes. |
| */</font> |
| <font color=#7F0055>public final</font> Map<String,Object> attributes; |
| |
| <font color=#7F0055>public</font> FileAttrs(<font color=#7F0055>int</font> flags, <font color=#7F0055>long</font> size, <font color=#7F0055>int</font> uid, <font color=#7F0055>int</font> gid, |
| <font color=#7F0055>int</font> permissions, <font color=#7F0055>long</font> atime, <font color=#7F0055>long</font> mtime, Map<String,Object> attributes); |
| |
| <font color=#3F5FBF>/** |
| * 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. |
| */</font> |
| <font color=#7F0055>public boolean</font> isFile(); |
| |
| <font color=#3F5FBF>/** |
| * 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. |
| */</font> |
| <font color=#7F0055>public boolean</font> isDirectory(); |
| } |
| |
| <font color=#3F5FBF>/** |
| * The following flags are defined for the 'permissions' field: |
| */</font> |
| <font color=#7F0055>static final int</font> |
| 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 permisson |
| S_IXOTH = 00001; // others have execute permission |
| |
| <font color=#7F0055>final static class</font> DirEntry { |
| <font color=#3F5FBF>/** |
| * `filename' is a file name being returned. It is a relative name within |
| * the directory, without any path components; |
| */</font> |
| <font color=#7F0055>public final</font> String filename; |
| |
| <font color=#3F5FBF>/** |
| * `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. |
| */</font> |
| <font color=#7F0055>public final</font> String longname; |
| |
| <font color=#3F5FBF>/** |
| * `attrs' is the attributes of the file. |
| */</font> |
| <font color=#7F0055>public final</font> FileAttrs attrs; |
| |
| <font color=#7F0055>public</font> DirEntry(String filename, String longname, FileAttrs attrs); |
| } |
| |
| <font color=#3F5FBF>/** |
| * Opaque representation of open file handle. |
| * Note: open file handle can be used only with service instance that |
| * created the handle. |
| */</font> |
| <font color=#7F0055>interface</font> IFileHandle { |
| IFileSystem getService(); |
| } |
| |
| <font color=#3F5FBF>/** |
| * Service specific error codes. |
| */</font> |
| <font color=#7F0055>static final int</font> |
| |
| <font color=#3F5FBF>/** |
| * 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. |
| */</font> |
| STATUS_EOF = 0x10001, |
| |
| <font color=#3F5FBF>/** |
| * This code is returned when a reference is made to a file which |
| * should exist but doesn't. |
| */</font> |
| STATUS_NO_SUCH_FILE = 0x10002, |
| |
| <font color=#3F5FBF>/** |
| * is returned when the authenticated user does not have sufficient |
| * permissions to perform the operation. |
| */</font> |
| STATUS_PERMISSION_DENIED = 0x10003; |
| |
| |
| <font color=#3F5FBF>/** |
| * The class to represent File System error reports. |
| */</font> |
| <font color=#7F0055>abstract static class</font> FileSystemException extends IOException { |
| |
| <font color=#7F0055>protected</font> FileSystemException(String message); |
| |
| <font color=#7F0055>protected</font> FileSystemException(Exception x) |
| |
| <font color=#3F5FBF>/** |
| * Get error code. The code can be standard TCF error code or |
| * one of service specific codes, see STATUS_*. |
| * @return error code. |
| */</font> |
| <font color=#7F0055>public abstract int</font> getStatus(); |
| } |
| |
| <font color=#3F5FBF>/** |
| * 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. |
| */</font> |
| IToken open(String file_name, <font color=#7F0055>int</font> flags, FileAttrs attrs, DoneOpen done); |
| |
| <font color=#7F0055>interface</font> DoneOpen { |
| <font color=#7F0055>void</font> doneOpen(IToken token, FileSystemException error, IFileHandle handle); |
| } |
| |
| <font color=#3F5FBF>/** |
| * 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. |
| */</font> |
| IToken close(IFileHandle handle, DoneClose done); |
| |
| <font color=#7F0055>interface</font> DoneClose { |
| <font color=#7F0055>void</font> doneClose(IToken token, FileSystemException error); |
| } |
| |
| <font color=#3F5FBF>/** |
| * 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. |
| * @param len is the maximum number of bytes to read. |
| * @param done is call back object. |
| * @return pending command handle. |
| */</font> |
| IToken read(IFileHandle handle, long offset, <font color=#7F0055>int</font> len, DoneRead done); |
| |
| <font color=#7F0055>interface</font> DoneRead { |
| <font color=#7F0055>void</font> doneRead(IToken token, FileSystemException error, byte[] data, boolean eof); |
| } |
| |
| <font color=#3F5FBF>/** |
| * 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. |
| * @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. |
| */</font> |
| IToken write(IFileHandle handle, long offset, |
| byte[] data, <font color=#7F0055>int</font> data_pos, <font color=#7F0055>int</font> data_size, DoneWrite done); |
| |
| <font color=#7F0055>interface</font> DoneWrite { |
| <font color=#7F0055>void</font> doneWrite(IToken token, FileSystemException error); |
| } |
| |
| <font color=#3F5FBF>/** |
| * 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. |
| */</font> |
| IToken stat(String path, DoneStat done); |
| |
| <font color=#3F5FBF>/** |
| * 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. |
| */</font> |
| IToken lstat(String path, DoneStat done); |
| |
| <font color=#3F5FBF>/** |
| * 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. |
| */</font> |
| IToken fstat(IFileHandle handle, DoneStat done); |
| |
| <font color=#7F0055>interface</font> DoneStat { |
| <font color=#7F0055>void</font> doneStat(IToken token, FileSystemException error, FileAttrs attrs); |
| } |
| |
| <font color=#3F5FBF>/** |
| * 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. |
| */</font> |
| IToken setstat(String path, FileAttrs attrs, DoneSetStat done); |
| |
| <font color=#3F5FBF>/** |
| * 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. |
| */</font> |
| IToken fsetstat(IFileHandle handle, FileAttrs attrs, DoneSetStat done); |
| |
| <font color=#7F0055>interface</font> DoneSetStat { |
| <font color=#7F0055>void</font> doneSetStat(IToken token, FileSystemException error); |
| } |
| |
| <font color=#3F5FBF>/** |
| * 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. |
| */</font> |
| IToken opendir(String path, DoneOpen done); |
| |
| <font color=#3F5FBF>/** |
| * 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. |
| */</font> |
| IToken readdir(IFileHandle handle, DoneReadDir done); |
| |
| <font color=#7F0055>interface</font> DoneReadDir { |
| <font color=#7F0055>void</font> doneReadDir(IToken token, FileSystemException error, DirEntry[] entries, boolean eof); |
| } |
| |
| <font color=#3F5FBF>/** |
| * 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. |
| */</font> |
| IToken mkdir(String path, FileAttrs attrs, DoneMkDir done); |
| |
| <font color=#7F0055>interface</font> DoneMkDir { |
| <font color=#7F0055>void</font> doneMkDir(IToken token, FileSystemException error); |
| } |
| |
| <font color=#3F5FBF>/** |
| * 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. |
| */</font> |
| IToken rmdir(String path, DoneRemove done); |
| |
| <font color=#7F0055>interface</font> DoneRemove { |
| <font color=#7F0055>void</font> doneRemove(IToken token, FileSystemException error); |
| } |
| |
| <font color=#3F5FBF>/** |
| * 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. |
| */</font> |
| IToken roots(DoneRoots done); |
| |
| <font color=#7F0055>interface</font> DoneRoots { |
| <font color=#7F0055>void</font> doneRoots(IToken token, FileSystemException error, DirEntry[] entries); |
| } |
| |
| <font color=#3F5FBF>/** |
| * 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. |
| */</font> |
| IToken remove(String file_name, DoneRemove done); |
| |
| <font color=#3F5FBF>/** |
| * 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. |
| */</font> |
| IToken realpath(String path, DoneRealPath done); |
| |
| <font color=#7F0055>interface</font> DoneRealPath { |
| <font color=#7F0055>void</font> doneRealPath(IToken token, FileSystemException error, String path); |
| } |
| |
| <font color=#3F5FBF>/** |
| * 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. |
| */</font> |
| IToken rename(String old_path, String new_path, DoneRename done); |
| |
| <font color=#7F0055>interface</font> DoneRename { |
| <font color=#7F0055>void</font> doneRename(IToken token, FileSystemException error); |
| } |
| |
| <font color=#3F5FBF>/** |
| * 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. |
| */</font> |
| IToken readlink(String path, DoneReadLink done); |
| |
| <font color=#7F0055>interface</font> DoneReadLink { |
| <font color=#7F0055>void</font> doneReadLink(IToken token, FileSystemException error, String path); |
| } |
| |
| <font color=#3F5FBF>/** |
| * 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. |
| */</font> |
| IToken symlink(String link_path, String target_path, DoneSymLink done); |
| |
| <font color=#7F0055>interface</font> DoneSymLink { |
| <font color=#7F0055>void</font> doneSymLink(IToken token, FileSystemException error); |
| } |
| |
| <font color=#3F5FBF>/** |
| * 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. |
| */</font> |
| IToken copy(String src_path, String dst_path, |
| boolean copy_permissions, boolean copy_ownership, DoneCopy done); |
| |
| <font color=#7F0055>interface</font> DoneCopy { |
| <font color=#7F0055>void</font> doneCopy(IToken token, FileSystemException error); |
| } |
| |
| <font color=#3F5FBF>/** |
| * 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. |
| */</font> |
| IToken user(DoneUser done); |
| |
| <font color=#7F0055>interface</font> DoneUser { |
| <font color=#7F0055>void</font> doneUser(IToken token, FileSystemException error, |
| <font color=#7F0055>int</font> real_uid, <font color=#7F0055>int</font> effective_uid, <font color=#7F0055>int</font> real_gid, <font color=#7F0055>int</font> effective_gid, |
| String home); |
| } |
| } |
| </pre> |
| |
| </body> |
| </html> |