psftp.h

   1 /*
   2  * psftp.h: interface between psftp.c / scp.c and each
   3  * platform-specific SFTP module.
   4  */
   5
   6 #include "int64.h"
   7
   8 #ifndef PUTTY_PSFTP_H
   9 #define PUTTY_PSFTP_H
  10
  11 /*
  12  * psftp_getcwd returns the local current directory. The returned
  13  * string must be freed by the caller.
  14  */
  15 char *psftp_getcwd(void);
  16
  17 /*
  18  * psftp_lcd changes the local current directory. The return value
  19  * is NULL on success, or else an error message which must be freed
  20  * by the caller.
  21  */
  22 char *psftp_lcd(char *newdir);
  23
  24 /*
  25  * Retrieve file times on a local file. Must return two unsigned
  26  * longs in POSIX time_t format.
  27  */
  28 void get_file_times(char *filename, unsigned long *mtime,
  29                     unsigned long *atime);
  30
  31 /*
  32  * One iteration of the PSFTP event loop: wait for network data and
  33  * process it, once.
  34  */
  35 int ssh_sftp_loop_iteration(void);
  36
  37 /*
  38  * Read a command line for PSFTP from standard input. Caller must
  39  * free.
  40  *
  41  * If `backend_required' is TRUE, should also listen for activity
  42  * at the backend (rekeys, clientalives, unexpected closures etc)
  43  * and respond as necessary, and if the backend closes it should
  44  * treat this as a failure condition. If `backend_required' is
  45  * FALSE, a back end is not (intentionally) active at all (e.g.
  46  * psftp before an `open' command).
  47  */
  48 char *ssh_sftp_get_cmdline(const char *prompt, int backend_required);
  49
  50 /*
  51  * Platform-specific function called when we're about to make a
  52  * network connection.
  53  */
  54 void platform_psftp_pre_conn_setup(void);
  55
  56 /*
  57  * The main program in psftp.c. Called from main() in the platform-
  58  * specific code, after doing any platform-specific initialisation.
  59  */
  60 int psftp_main(int argc, char *argv[]);
  61
  62 /*
  63  * These functions are used by PSCP to transmit progress updates
  64  * and error information to a GUI window managing it. This will
  65  * probably only ever be supported on Windows, so these functions
  66  * can safely be stubs on all other platforms.
  67  */
  68 void gui_update_stats(const char *name, unsigned long size,
  69                       int percentage, unsigned long elapsed,
  70                       unsigned long done, unsigned long eta,
  71                       unsigned long ratebs);
  72 void gui_send_errcount(int list, int errs);
  73 void gui_send_char(int is_stderr, int c);
  74 void gui_enable(const char *arg);
  75
  76 /*
  77  * It's likely that a given platform's implementation of file
  78  * transfer utilities is going to want to do things with them that
  79  * aren't present in stdio. Hence we supply an alternative
  80  * abstraction for file access functions.
  81  *
  82  * This abstraction tells you the size and access times when you
  83  * open an existing file (platforms may choose the meaning of the
  84  * file times if it's not clear; whatever they choose will be what
  85  * PSCP sends to the server as mtime and atime), and lets you set
  86  * the times when saving a new file.
  87  *
  88  * On the other hand, the abstraction is pretty simple: it supports
  89  * only opening a file and reading it, or creating a file and writing
  90  * it. None of this read-and-write, seeking-back-and-forth stuff.
  91  */
  92 typedef struct RFile RFile;
  93 typedef struct WFile WFile;
  94 /* Output params size, perms, mtime and atime can all be NULL if
  95  * desired. perms will be -1 if the OS does not support POSIX permissions. */
  96 RFile *open_existing_file(const char *name, uint64 *size,
  97                           unsigned long *mtime, unsigned long *atime,
  98                           long *perms);
  99 WFile *open_existing_wfile(const char *name, uint64 *size);
 100 /* Returns <0 on error, 0 on eof, or number of bytes read, as usual */
 101 int read_from_file(RFile *f, void *buffer, int length);
 102 /* Closes and frees the RFile */
 103 void close_rfile(RFile *f);
 104 WFile *open_new_file(const char *name, long perms);
 105 /* Returns <0 on error, 0 on eof, or number of bytes written, as usual */
 106 int write_to_file(WFile *f, void *buffer, int length);
 107 void set_file_times(WFile *f, unsigned long mtime, unsigned long atime);
 108 /* Closes and frees the WFile */
 109 void close_wfile(WFile *f);
 110 /* Seek offset bytes through file */
 111 enum { FROM_START, FROM_CURRENT, FROM_END };
 112 int seek_file(WFile *f, uint64 offset, int whence);
 113 /* Get file position */
 114 uint64 get_file_posn(WFile *f);
 115 /*
 116  * Determine the type of a file: nonexistent, file, directory or
 117  * weird. `weird' covers anything else - named pipes, Unix sockets,
 118  * device files, fish, badgers, you name it. Things marked `weird'
 119  * will be skipped over in recursive file transfers, so the only
 120  * real reason for not lumping them in with `nonexistent' is that
 121  * it allows a slightly more sane error message.
 122  */
 123 enum {
 124     FILE_TYPE_NONEXISTENT, FILE_TYPE_FILE, FILE_TYPE_DIRECTORY, FILE_TYPE_WEIRD
 125 };
 126 int file_type(const char *name);
 127
 128 /*
 129  * Read all the file names out of a directory.
 130  */
 131 typedef struct DirHandle DirHandle;
 132 DirHandle *open_directory(const char *name);
 133 /* The string returned from this will need freeing if not NULL */
 134 char *read_filename(DirHandle *dir);
 135 void close_directory(DirHandle *dir);
 136
 137 /*
 138  * Test a filespec to see whether it's a local wildcard or not.
 139  * Return values:
 140  *
 141  *  - WCTYPE_WILDCARD (this is a wildcard).
 142  *  - WCTYPE_FILENAME (this is a single file name).
 143  *  - WCTYPE_NONEXISTENT (whichever it was, nothing of that name exists).
 144  *
 145  * Some platforms may choose not to support local wildcards when
 146  * they come from the command line; in this case they simply never
 147  * return WCTYPE_WILDCARD, but still test the file's existence.
 148  * (However, all platforms will probably want to support wildcards
 149  * inside the PSFTP CLI.)
 150  */
 151 enum {
 152     WCTYPE_NONEXISTENT, WCTYPE_FILENAME, WCTYPE_WILDCARD
 153 };
 154 int test_wildcard(const char *name, int cmdline);
 155
 156 /*
 157  * Actually return matching file names for a local wildcard.
 158  */
 159 typedef struct WildcardMatcher WildcardMatcher;
 160 WildcardMatcher *begin_wildcard_matching(const char *name);
 161 /* The string returned from this will need freeing if not NULL */
 162 char *wildcard_get_filename(WildcardMatcher *dir);
 163 void finish_wildcard_matching(WildcardMatcher *dir);
 164
 165 /*
 166  * Vet a filename returned from the remote host, to ensure it isn't
 167  * in some way malicious. The idea is that this function is applied
 168  * to filenames returned from FXP_READDIR, which means we can panic
 169  * if we see _anything_ resembling a directory separator.
 170  *
 171  * Returns TRUE if the filename is kosher, FALSE if dangerous.
 172  */
 173 int vet_filename(const char *name);
 174
 175 /*
 176  * Create a directory. Returns 0 on error, !=0 on success.
 177  */
 178 int create_directory(const char *name);
 179
 180 /*
 181  * Concatenate a directory name and a file name. The way this is
 182  * done will depend on the OS.
 183  */
 184 char *dir_file_cat(const char *dir, const char *file);
 185
 186 /*
 187  * Return a pointer to the portion of str that comes after the last
 188  * path component separator.
 189  *
 190  * If 'local' is false, path component separators are taken to just be
 191  * '/', on the assumption that we're discussing the path syntax on the
 192  * server. But if 'local' is true, the separators are whatever the
 193  * local OS will treat that way - so that includes '\' and ':' on
 194  * Windows.
 195  *
 196  * This function has the annoying strstr() property of taking a const
 197  * char * and returning a char *. You should treat it as if it was a
 198  * pair of overloaded functions, one mapping mutable->mutable and the
 199  * other const->const :-(
 200  */
 201 char *stripslashes(const char *str, int local);
 202
 203 #endif /* PUTTY_PSFTP_H */