src/pthr_ftpc.h

   1 /* FTP client library.
   2  * - by Richard W.M. Jones <rich@annexia.org>
   3  *
   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.
   8  *
   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.
  13  *
  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.
  17  *
  18  * $Id: pthr_ftpc.h,v 1.5 2002/12/01 14:29:27 rich Exp $
  19  */
  20
  21 #ifndef PTHR_FTPC_H
  22 #define PTHR_FTPC_H
  23
  24 #include <pool.h>
  25 #include <vector.h>
  26
  27 #include <pthr_pseudothread.h>
  28 #include <pthr_iolib.h>
  29
  30 struct ftpc;
  31 typedef struct ftpc *ftpc;
  32
  33 /* Function: new_ftpc - Create a new FTP client object.
  34  *
  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.
  39  *
  40  * The default mode for new connections is active mode. Call
  41  * @ref{ftpc_set_mode(3)} to change the mode.
  42  *
  43  * See also: @ref{ftpc_login(3)}, @ref{ftpc_set_mode(3)}.
  44  */
  45 extern ftpc new_ftpc (pool, const char *server);
  46
  47 /* Function: ftpc_set_passive_mode - Change to/from active or passive mode.
  48  *
  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.
  52  *
  53  * Passive mode is required by a few servers and some firewalls.
  54  *
  55  * Returns: 0 if successful, -1 if the attempt failed.
  56  * If a fatal error occurs with the connection, an exception
  57  * is thrown.
  58  */
  59 extern int ftpc_set_passive_mode (ftpc ftpc, int flag);
  60
  61 extern int ftpc_set_verbose (ftpc ftpc, int flag);
  62
  63 extern void ftpc_perror (ftpc f, const char *msg);
  64
  65 /* Function: ftpc_login - Log onto the FTP server.
  66  *
  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.
  73  *
  74  * Returns: 0 if successful, -1 if the attempt failed.
  75  * If a fatal error occurs with the connection, an exception
  76  * is thrown.
  77  */
  78 extern int ftpc_login (ftpc ftpc, const char *username, const char *password);
  79
  80 /* Function: ftpc_type - Set connection type.
  81  * Function: ftpc_ascii
  82  * Function: ftpc_binary
  83  *
  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).
  87  *
  88  * @code{ftpc_ascii} sets the type to ASCII.
  89  *
  90  * @code{ftpc_binary} sets the type to bInary.
  91  *
  92  * Returns: 0 if successful, -1 if the attempt failed.
  93  * If a fatal error occurs with the connection, an exception
  94  * is thrown.
  95  */
  96 extern int ftpc_type (ftpc ftpc, char type);
  97 extern int ftpc_ascii (ftpc ftpc);
  98 extern int ftpc_binary (ftpc ftpc);
  99
 100 /* Function: ftpc_cwd - Change directory on the server.
 101  * Function: ftpc_cdup
 102  *
 103  * @code{ftpc_cwd} changes the directory to @code{pathname}.
 104  *
 105  * @code{ftpc_cdup} moves to the parent directory. On most Unix-like
 106  * FTP servers this is equivalent to doing @code{CWD ..}
 107  *
 108  * Returns: 0 if successful, -1 if the attempt failed.
 109  * If a fatal error occurs with the connection, an exception
 110  * is thrown.
 111  */
 112 extern int ftpc_cwd (ftpc ftpc, const char *pathname);
 113 extern int ftpc_cdup (ftpc ftpc);
 114
 115 /* Function: ftpc_pwd - Return current directory on the server.
 116  *
 117  * @code{ftpc_pwd} returns the current directory on the server.
 118  *
 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.
 122  */
 123 extern char *ftpc_pwd (ftpc ftpc);
 124
 125 /* Function: ftpc_mkdir - Create or remove directories on the server.
 126  * Function: ftpc_rmdir
 127  *
 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.
 131  *
 132  * Returns: 0 if successful, -1 if the attempt failed.
 133  * If a fatal error occurs with the connection, an exception
 134  * is thrown.
 135  */
 136 extern int ftpc_mkdir (ftpc ftpc, const char *pathname);
 137 extern int ftpc_rmdir (ftpc ftpc, const char *pathname);
 138
 139 /* Function: ftpc_delete - Delete a file on the server.
 140  *
 141  * @code{ftpc_delete} deletes a file called @code{pathname}
 142  * on the server.
 143  *
 144  * Returns: 0 if successful, -1 if the attempt failed.
 145  * If a fatal error occurs with the connection, an exception
 146  * is thrown.
 147  */
 148 extern int ftpc_delete (ftpc ftpc, const char *pathname);
 149
 150 /* Function: ftpc_ls - List the contents of a directory on the server.
 151  * Function: ftpc_dir
 152  *
 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}.
 156  *
 157  * @code{ftpc_ls} issues the command @code{NLST -a}, returning a
 158  * vector of strings giving the name of each file.
 159  *
 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.
 163  *
 164  * Returns: 0 if successful, -1 if the attempt failed.
 165  * If a fatal error occurs with the connection, an exception
 166  * is thrown.
 167  */
 168 extern vector ftpc_ls (ftpc ftpc, pool, const char *pathname);
 169 extern vector ftpc_dir (ftpc ftpc, pool, const char *pathname);
 170
 171 /* Function: ftpc_get - Download or upload a file.
 172  * Function: ftpc_put
 173  *
 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}.
 176  *
 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}.
 180  *
 181  * Returns: 0 if successful, -1 if the attempt failed.
 182  * If a fatal error occurs with the connection, an exception
 183  * is thrown.
 184  */
 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);
 187
 188 /* Function: ftpc_quote - Issue a command to the FTP server.
 189  *
 190  * @code{ftpc_quote} issues a command directly to the FTP server.
 191  * This function may be used for issuing @code{SITE} commands for
 192  * example.
 193  *
 194  * Returns: 0 if successful, -1 if the attempt failed.
 195  * If a fatal error occurs with the connection, an exception
 196  * is thrown.
 197  */
 198 extern int ftpc_quote (ftpc ftpc, const char *cmd);
 199
 200 /* Function: ftpc_quit - Nicely disconnect from the FTP server.
 201  *
 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.
 206  *
 207  * Returns: 0 if successful, -1 if the attempt failed.
 208  * If a fatal error occurs with the connection, an exception
 209  * is thrown.
 210  */
 211 extern int ftpc_quit (ftpc ftpc);
 212
 213 #endif /* PTHR_FTPC_H */