Mercurial > 510Connectbot

comparison app/src/main/java/ch/ethz/ssh2/SFTPClient.java @ 438:d29cce60f393

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
migrate from Eclipse to Android Studio
author Carl Byington <carl@five-ten-sg.com>
date Thu, 03 Dec 2015 11:23:55 -0800
parents src/ch/ethz/ssh2/SFTPClient.java@91a31873c42a
children
comparison
equal deleted inserted replaced
437:208b31032318 438:d29cce60f393
1 package ch.ethz.ssh2;
2
3 import java.io.IOException;
4 import java.util.List;
5
6 /**
7 * @version $Id: SFTPClient.java 151 2014-04-28 10:03:39Z dkocher@sudo.ch $
8 */
9 public interface SFTPClient {
10
11 /**
12 * Retrieve the file attributes of an open file.
13 *
14 * @param handle a SFTPv3FileHandle handle.
15 * @return a SFTPv3FileAttributes object.
16 * @throws IOException
17 */
18 SFTPFileAttributes fstat(SFTPFileHandle handle) throws IOException;
19
20 /**
21 * Retrieve the file attributes of a file. This method
22 * follows symbolic links on the server.
23 *
24 * @param path See the {@link SFTPClient comment} for the class for more details.
25 * @return a SFTPv3FileAttributes object.
26 * @throws IOException
27 * @see #lstat(String)
28 */
29 SFTPFileAttributes stat(String path) throws IOException;
30
31 /**
32 * Retrieve the file attributes of a file. This method
33 * does NOT follow symbolic links on the server.
34 *
35 * @param path See the {@link SFTPClient comment} for the class for more details.
36 * @return a SFTPv3FileAttributes object.
37 * @throws IOException
38 * @see #stat(String)
39 */
40 SFTPFileAttributes lstat(String path) throws IOException;
41
42 /**
43 * Read the target of a symbolic link. Note: OpenSSH (as of version 4.4) gets very upset
44 * (SSH_FX_BAD_MESSAGE error) if you want to read the target of a file that is not a
45 * symbolic link. Better check first with {@link #lstat(String)}.
46 *
47 * @param path See the {@link SFTPClient comment} for the class for more details.
48 * @return The target of the link.
49 * @throws IOException
50 */
51 String readLink(String path) throws IOException;
52
53 /**
54 * Modify the attributes of a file. Used for operations such as changing
55 * the ownership, permissions or access times, as well as for truncating a file.
56 *
57 * @param path See the {@link SFTPClient comment} for the class for more details.
58 * @param attr A SFTPv3FileAttributes object. Specifies the modifications to be
59 * made to the attributes of the file. Empty fields will be ignored.
60 * @throws IOException
61 */
62 void setstat(String path, SFTPFileAttributes attr) throws IOException;
63
64 /**
65 * Modify the attributes of a file. Used for operations such as changing
66 * the ownership, permissions or access times, as well as for truncating a file.
67 *
68 * @param handle a SFTPv3FileHandle handle
69 * @param attr A SFTPv3FileAttributes object. Specifies the modifications to be
70 * made to the attributes of the file. Empty fields will be ignored.
71 * @throws IOException
72 */
73 void fsetstat(SFTPFileHandle handle, SFTPFileAttributes attr) throws IOException;
74
75 /**
76 * Create a symbolic link on the server. Creates a link "src" that points
77 * to "target".
78 *
79 * @param src See the {@link SFTPClient comment} for the class for more details.
80 * @param target See the {@link SFTPClient comment} for the class for more details.
81 * @throws IOException
82 */
83 void createSymlink(String src, String target) throws IOException;
84
85 /**
86 * Create a symbolic link on the server. Creates a link "src" that points
87 * to "target".
88 *
89 * @param src See the {@link SFTPClient comment} for the class for more details.
90 * @param target See the {@link SFTPClient comment} for the class for more details.
91 * @throws IOException
92 */
93 void createHardlink(String src, String target) throws IOException;
94
95 /**
96 * Have the server canonicalize any given path name to an absolute path.
97 * This is useful for converting path names containing ".." components or
98 * relative pathnames without a leading slash into absolute paths.
99 *
100 * @param path See the {@link SFTPClient comment} for the class for more details.
101 * @return An absolute path.
102 * @throws IOException
103 */
104 String canonicalPath(String path) throws IOException;
105
106 void setCharset(String charset) throws IOException;
107
108 String getCharset();
109
110 SFTPFileHandle openDirectory(String path) throws IOException;
111
112 boolean isConnected();
113
114 void close();
115
116 List<? extends SFTPDirectoryEntry> ls(String dirName) throws IOException;
117
118 /**
119 * Create a new directory.
120 *
121 * @param name See the {@link SFTPClient comment} for the class for more details.
122 * @param posixPermissions the permissions for this directory, e.g., "0700" (remember that
123 * this is octal noation). The server will likely apply a umask.
124 * @throws IOException
125 */
126 void mkdir(String name, int posixPermissions) throws IOException;
127
128 /**
129 * Remove a file.
130 *
131 * @param filename See the {@link SFTPClient comment} for the class for more details.
132 * @throws IOException
133 */
134 void rm(String filename) throws IOException;
135
136 /**
137 * Remove an empty directory.
138 *
139 * @param dirName See the {@link SFTPClient comment} for the class for more details.
140 * @throws IOException
141 */
142 void rmdir(String dirName) throws IOException;
143
144 /**
145 * Move a file or directory.
146 *
147 * @param oldPath See the {@link SFTPClient comment} for the class for more details.
148 * @param newPath See the {@link SFTPClient comment} for the class for more details.
149 * @throws IOException
150 */
151 void mv(String oldPath, String newPath) throws IOException;
152
153 /**
154 * Create a file and open it for reading and writing.
155 * Same as {@link #createFile(String, SFTPFileAttributes) createFile(filename, null)}.
156 *
157 * @param filename See the {@link SFTPClient comment} for the class for more details.
158 * @return a SFTPv3FileHandle handle
159 * @throws IOException
160 */
161 SFTPFileHandle createFile(String filename) throws IOException;
162
163 /**
164 * Create a file and open it for reading and writing.
165 * You can specify the default attributes of the file (the server may or may
166 * not respect your wishes).
167 *
168 * @param filename See the {@link SFTPv3Client comment} for the class for more details.
169 * @param attr may be <code>null</code> to use server defaults. Probably only
170 * the <code>uid</code>, <code>gid</code> and <code>permissions</code>
171 * (remember the server may apply a umask) entries of the {@link SFTPv3FileHandle}
172 * structure make sense. You need only to set those fields where you want
173 * to override the server's defaults.
174 * @return a SFTPv3FileHandle handle
175 * @throws IOException
176 */
177 SFTPFileHandle createFile(String filename, SFTPFileAttributes attr) throws IOException;
178
179 SFTPFileHandle openFile(String filename, int flags) throws IOException;
180
181 /**
182 * Read bytes from a file in a parallel fashion. As many bytes as you want will be read.
183 * <p/>
184 * <ul>
185 * <li>The server will read as many bytes as it can from the file (up to <code>len</code>),
186 * and return them.</li>
187 * <li>If EOF is encountered before reading any data, <code>-1</code> is returned.
188 * <li>If an error occurs, an exception is thrown</li>.
189 * <li>For normal disk files, it is guaranteed that the server will return the specified
190 * number of bytes, or up to end of file. For, e.g., device files this may return
191 * fewer bytes than requested.</li>
192 * </ul>
193 *
194 * @param handle a SFTPv3FileHandle handle
195 * @param fileOffset offset (in bytes) in the file
196 * @param dst the destination byte array
197 * @param dstoff offset in the destination byte array
198 * @param len how many bytes to read, 0 &lt; len
199 * @return the number of bytes that could be read, may be less than requested if
200 * the end of the file is reached, -1 is returned in case of <code>EOF</code>
201 * @throws IOException
202 */
203 int read(SFTPFileHandle handle, long fileOffset, byte[] dst, int dstoff, int len) throws IOException;
204
205 /**
206 * Write bytes to a file. If <code>len</code> &gt; 32768, then the write operation will
207 * be split into multiple writes.
208 *
209 * @param handle a SFTPv3FileHandle handle.
210 * @param fileOffset offset (in bytes) in the file.
211 * @param src the source byte array.
212 * @param srcoff offset in the source byte array.
213 * @param len how many bytes to write.
214 * @throws IOException
215 */
216 void write(SFTPFileHandle handle, long fileOffset, byte[] src, int srcoff, int len) throws IOException;
217
218 /**
219 * Close a file.
220 *
221 * @param handle a file handle
222 * @throws IOException
223 */
224 void closeFile(SFTPFileHandle handle) throws IOException;
225 }