2 * - by Richard W.M. Jones <rich@annexia.org>
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Library General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Library General Public License for more details.
14 * You should have received a copy of the GNU Library General Public
15 * License along with this library; if not, write to the Free
16 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
18 * $Id: pthr_ftpc.h,v 1.5 2002/12/01 14:29:27 rich Exp $
27 #include <pthr_pseudothread.h>
28 #include <pthr_iolib.h>
31 typedef struct ftpc *ftpc;
33 /* Function: new_ftpc - Create a new FTP client object.
35 * Create a new FTP client object, connected to the FTP server
36 * called @code{server}. The @code{server} may be an IP address or a hostname.
37 * If the @code{server} name ends with @code{:port} then @code{port}
38 * is the port number to connect to.
40 * The default mode for new connections is active mode. Call
41 * @ref{ftpc_set_mode(3)} to change the mode.
43 * See also: @ref{ftpc_login(3)}, @ref{ftpc_set_mode(3)}.
45 extern ftpc new_ftpc (pool, const char *server);
47 /* Function: ftpc_set_passive_mode - Change to/from active or passive mode.
49 * If @code{flag} is true, all future connections on this @code{ftpc}
50 * object will be in passive mode. If @code{flag} is false, all
51 * future connections will be in active mode.
53 * Passive mode is required by a few servers and some firewalls.
55 * Returns: 0 if successful, -1 if the attempt failed.
56 * If a fatal error occurs with the connection, an exception
59 extern int ftpc_set_passive_mode (ftpc ftpc, int flag);
61 extern int ftpc_set_verbose (ftpc ftpc, int flag);
63 extern void ftpc_perror (ftpc f, const char *msg);
65 /* Function: ftpc_login - Log onto the FTP server.
67 * Attempt to log onto the FTP server as user @code{username} with
68 * password @code{password}. If @code{username} is @code{NULL},
69 * @code{"ftp"} or @code{"anonymous"}, then log in anonymously.
70 * For anonymous logins, the @code{password} may be @code{NULL},
71 * in which case the environment variable @code{LOGNAME} followed
72 * by a single @code{@} character is used as the password.
74 * Returns: 0 if successful, -1 if the attempt failed.
75 * If a fatal error occurs with the connection, an exception
78 extern int ftpc_login (ftpc ftpc, const char *username, const char *password);
80 /* Function: ftpc_type - Set connection type.
81 * Function: ftpc_ascii
82 * Function: ftpc_binary
84 * @code{ftpc_type} sets the connection type. Most FTP servers only
85 * support type 'a' (ASCII) or type 'i' (bInary), although esoteric
86 * FTP servers might support 'e' (EBCDIC).
88 * @code{ftpc_ascii} sets the type to ASCII.
90 * @code{ftpc_binary} sets the type to bInary.
92 * Returns: 0 if successful, -1 if the attempt failed.
93 * If a fatal error occurs with the connection, an exception
96 extern int ftpc_type (ftpc ftpc, char type);
97 extern int ftpc_ascii (ftpc ftpc);
98 extern int ftpc_binary (ftpc ftpc);
100 /* Function: ftpc_cwd - Change directory on the server.
101 * Function: ftpc_cdup
103 * @code{ftpc_cwd} changes the directory to @code{pathname}.
105 * @code{ftpc_cdup} moves to the parent directory. On most Unix-like
106 * FTP servers this is equivalent to doing @code{CWD ..}
108 * Returns: 0 if successful, -1 if the attempt failed.
109 * If a fatal error occurs with the connection, an exception
112 extern int ftpc_cwd (ftpc ftpc, const char *pathname);
113 extern int ftpc_cdup (ftpc ftpc);
115 /* Function: ftpc_pwd - Return current directory on the server.
117 * @code{ftpc_pwd} returns the current directory on the server.
119 * Returns: The current directory, as a string allocated in the
120 * pool, or NULL if the command fails. If a fatal error occurs
121 * with the connection, an exception is thrown.
123 extern char *ftpc_pwd (ftpc ftpc);
125 /* Function: ftpc_mkdir - Create or remove directories on the server.
126 * Function: ftpc_rmdir
128 * @code{ftpc_mkdir} creates a directory called @code{pathname}
129 * on the server. @code{ftpc_rmdir} removes a directory called
130 * @code{pathname} on the server.
132 * Returns: 0 if successful, -1 if the attempt failed.
133 * If a fatal error occurs with the connection, an exception
136 extern int ftpc_mkdir (ftpc ftpc, const char *pathname);
137 extern int ftpc_rmdir (ftpc ftpc, const char *pathname);
139 /* Function: ftpc_delete - Delete a file on the server.
141 * @code{ftpc_delete} deletes a file called @code{pathname}
144 * Returns: 0 if successful, -1 if the attempt failed.
145 * If a fatal error occurs with the connection, an exception
148 extern int ftpc_delete (ftpc ftpc, const char *pathname);
150 /* Function: ftpc_ls - List the contents of a directory on the server.
153 * @code{ftpc_ls} and @code{ftpc_dir} list the contents of either
154 * the current directory (if @code{pathname} is @code{NULL}) or
155 * else another directory @code{pathname}.
157 * @code{ftpc_ls} issues the command @code{NLST -a}, returning a
158 * vector of strings giving the name of each file.
160 * @code{ftpc_dir} issues the command @code{LIST -a}, returning
161 * a human-readable list of filenames, similar to issuing the
162 * @code{ls -al} command in Unix.
164 * Returns: 0 if successful, -1 if the attempt failed.
165 * If a fatal error occurs with the connection, an exception
168 extern vector ftpc_ls (ftpc ftpc, pool, const char *pathname);
169 extern vector ftpc_dir (ftpc ftpc, pool, const char *pathname);
171 /* Function: ftpc_get - Download or upload a file.
174 * @code{ftpc_get} attempts to download @code{remote_file} from the
175 * server and store it in a local file called @code{local_file}.
177 * @code{ftpc_put} attempts to upload a file called @code{local_file}
178 * to the server and store it in a file on the server called
179 * @code{remote_file}.
181 * Returns: 0 if successful, -1 if the attempt failed.
182 * If a fatal error occurs with the connection, an exception
185 extern int ftpc_get (ftpc ftpc, const char *remote_file, const char *local_file);
186 extern int ftpc_put (ftpc ftpc, const char *local_file, const char *remote_file);
188 /* Function: ftpc_quote - Issue a command to the FTP server.
190 * @code{ftpc_quote} issues a command directly to the FTP server.
191 * This function may be used for issuing @code{SITE} commands for
194 * Returns: 0 if successful, -1 if the attempt failed.
195 * If a fatal error occurs with the connection, an exception
198 extern int ftpc_quote (ftpc ftpc, const char *cmd);
200 /* Function: ftpc_quit - Nicely disconnect from the FTP server.
202 * @code{ftpc_quit} sends a @code{QUIT} command to the FTP server
203 * and then drops the network connection. After using this function,
204 * the @code{ftpc} object associated with the connection is
205 * invalid and should not be used.
207 * Returns: 0 if successful, -1 if the attempt failed.
208 * If a fatal error occurs with the connection, an exception
211 extern int ftpc_quit (ftpc ftpc);
213 #endif /* PTHR_FTPC_H */