putty/PSFTP.H

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