← Back to branch summary

~ubuntu-branches/ubuntu/raring/ncbi-tools6/raring

« back to all changes in this revision

Viewing changes to connect/ncbi_ftp_connector.h

  • Committer: Package Import Robot
  • Author(s): Aaron M. Ucko
  • Date: 2011-09-05 18:55:02 UTC
  • mfrom: (1.1.11 upstream)
  • Revision ID: package-import@ubuntu.com-20110905185502-iuvmoe65ytljhckn
Tags: 6.1.20110713-1
* New upstream release.
* debian/*.symbols: update accordingly.
* make/makeshlb.unx: link libcn3dOGL.so against -lm for sqrt.
* doc/man/*.1: update for new release.
* debian/rules:
  - (VIB): add asnmacro, as upstream takes care to publish binaries thereof.
  - Retire obsolete multiarch-unaware checks for libpthread.
  - Fully modernize Debhelper usage; in particular, transition to overrides.
* debian/compat: advance to 9 per rules modernization.
* debian/ncbi-tools-bin.install: add asnmacro.
* make/makenet.unx: link asnmacro only against libraries it directly needs.
* doc/man/asnmacro.1: give asnmacro a man page.
* doc/man/Psequin.1: list it in SEE ALSO.
* network/id1arch/idfetch.c: revert redundant change (from #295110).
* Convert to multiarch.
  - debian/rules: Install libraries (and ncbithr.o) to multiarch directories.
  - debian/lib*.install: match multiarch library paths.
  - debian/control:
    + Build-Depends: debhelper (>= 8.1.3~), implying a recent dpkg-dev.
    + Set Multi-Arch: as appropriate across the board, and specify
      Pre-Depends: ${misc:Pre-Depends} for runtime libraries.
* debian/*.lintian-overrides: drop leading slashes for Lintian 2.5.x.
* debian/control: Standards-Version: 3.9.2 (already compliant).

Show diffs side-by-side

added added

removed removed

Lines of Context:
connect/ncbi_ftp_connector.h
1
1
#ifndef CONNECT___NCBI_FTP_CONNECTOR__H
2
2
#define CONNECT___NCBI_FTP_CONNECTOR__H
3
3
 
4
 
/* $Id: ncbi_ftp_connector.h,v 1.5 2010/05/21 12:34:38 kazimird Exp $
 
4
/* $Id: ncbi_ftp_connector.h,v 1.11 2011/05/26 19:09:31 kazimird Exp $
5
5
 * ===========================================================================
6
6
 *
7
7
 *                            PUBLIC DOMAIN NOTICE
38
38
 
39
39
#include <connect/ncbi_buffer.h>
40
40
#include <connect/ncbi_connector.h>
 
41
#include <connect/ncbi_connutil.h>
 
42
 
 
43
#ifndef NCBI_DEPRECATED
 
44
#  define NCBI_FTP_CONNECTOR_DEPRECATED
 
45
#else
 
46
#  define NCBI_FTP_CONNECTOR_DEPRECATED NCBI_DEPRECATED
 
47
#endif
41
48
 
42
49
 
43
50
/** @addtogroup Connectors
52
59
 
53
60
 
54
61
typedef enum {
55
 
    fFCDC_LogControl  = 1,
56
 
    fFCDC_LogData     = 2,
57
 
    fFCDC_LogAll      = fFCDC_LogControl | fFCDC_LogData,
58
 
    fFCDC_UseFeatures = 8
59
 
} EFCDC_Flags;
60
 
typedef unsigned int TFCDC_Flags;
61
 
 
62
 
typedef enum { /* DEPRECATED -- DON'T USE! */
63
 
    eFCDC_LogControl = fFCDC_LogControl,
64
 
    eFCDC_LogData    = fFCDC_LogData,
65
 
    eFCDC_LogAll     = fFCDC_LogAll
66
 
} EFCDC_OldFlags;
67
 
 
68
 
 
69
 
/* Create new CONNECTOR structure to handle ftp transfers,
70
 
 * both download and upload.
71
 
 * Return NULL on error.
72
 
 */
 
62
    fFTP_LogControl   = 0x01,
 
63
    fFTP_LogData      = 0x02,
 
64
    fFTP_LogAll       = fFTP_LogControl | fFTP_LogData,
 
65
    fFTP_UseFeatures  = 0x04,  /* parse FEAT to check for available FTP feats*/
 
66
    fFTP_NotifySize   = 0x08,  /* use C/B to communicate file size to user   */
 
67
    fFTP_UsePassive   = 0x10,  /* use only passive mode for data connection  */
 
68
    fFTP_UseActive    = 0x20,  /* use only active  mode for data connection  */
 
69
    fFTP_UseTypeL8    = 0x40,  /* use "TYPE L8" instead of "TYPE I" for data */
 
70
    fFTP_BypassProxy  = 0x80,  /* do not use HTTP proxy even if provided     */
 
71
    fFTP_NoSizeChecks = 0x100, /* do not check sizes of data transfers       */
 
72
    fFTP_UncorkUpload = 0x200, /* do not use TCP_CORK for uploads            */
 
73
} EFTP_Flags;
 
74
typedef unsigned int TFTP_Flags;  /* bitwise OR of ECONN_Flags               */
 
75
 
 
76
 
 
77
/* FTP protocol implies the use of both control connection (to pass commands
 
78
 * and responses) and data connection (to pass file contents), so is a 4-way
 
79
 * commmunication scheme.
 
80
 * CONN API supports only a two way scheme, which is why for FTP a special
 
81
 * discipline is required to communicate with the server.
 
82
 * User code interacts with FTP server by means of writing commands
 
83
 * (most of which are direct FTP commands, see below), and either reading
 
84
 * responses or file contents.  There is a special stop command to clear up
 
85
 * any pending command/action in progress.
 
86
 * Table below describes each command and what the user code is expected to do.
 
87
 *
 
88
 * Upon open, FTP server gets connected to with specified username and password
 
89
 * (user accounts [ACCT] are not supported), and the data transfer is set to be
 
90
 * STREAM/FILE/BINARY(I or L8) -- these transfer parameters may not be changed.
 
91
 *
 
92
 * Any disruption in control connection with server renders FTP connection bad
 
93
 * and unusable.  There is no automatic recovery (other than a full restart of
 
94
 * the connection) provided by the implementation.
 
95
 *
 
96
 * USER COMMAND(write) ACTION(server)          OUTPUT(to read on success)
 
97
 *
 
98
 * REN f1 f2           Rename file f1 to f2    250
 
99
 * CWD<SP>d            Change directory to d   250
 
100
 * PWD                 Get current directory   Current directory
 
101
 * MKD<SP>d            Create directory d      Directory created
 
102
 * RMD<SP>d            Delete directory d      250
 
103
 * CDUP                Go one dir level up     200
 
104
 * SYST                Get system info         Single-line system info
 
105
 * SIZE<SP>f           Get size of file f      Size of the file (numeric str)
 
106
 * MDTM<SP>f           Get time of file f      File time (UTC secs since epoch)
 
107
 * LIST[<SP>d]         List curdir / dir d     Full directory listing
 
108
 * NLST[<SP>d]         Short list as in LIST   Short dirlist (filenames only)
 
109
 * DELE<SP>f           Delete file f           250
 
110
 * RETR<SP>f           Retrieve file f         File contents
 
111
 * REST<SP>offset      Offset the transfer     350
 
112
 * NOOP[<SP>anything]  Abort current download  <EOF>
 
113
 * STOR<SP>f           Store file f on server
 
114
 * APPE<SP>f           Append/create file f
 
115
 * 
 
116
 * All commands above must be terminated with LF('\n') to be executed
 
117
 * (otherwise, successive writes are causing the command to continue to
 
118
 * accumulate in the internal command buffer).  Only one command can be
 
119
 * executed at a time (i.e. writing "CDUP\nSYST\n" in a single write is
 
120
 * illegal).  Note that the codes are text strings each consisting of 3 chars
 
121
 * (not ints!) -- the "values" are chosen to be equivalent to FTP response
 
122
 * codes that the FTP servers are expected to generate upon successful
 
123
 * completion of the corresponding commands (per RFC959), but may not always
 
124
 * be the actual codes received from the server (connector is flexible with
 
125
 * accepting various codes noted in several different implementation of FTP
 
126
 * servers).
 
127
 *
 
128
 * <SP> denotes exactly one space character, a blank means any number of space
 
129
 * or tab characters.  Single filenames(f) and directories(d) span up to the
 
130
 * end of the command ('\n'), and do not require any quoting for special
 
131
 * characters.  Exception is the REN command, which takes two names, f1 and f2,
 
132
 * with each being either a single token (no leading '"' and embedded spaces /
 
133
 * tabs), or quoted FTP-style (enclosed in double quotes, with any embedded
 
134
 * double quote character doubled, i.e. """a""b" encodes the file name "a"b).
 
135
 * Note that the filename a"b (no leading quote) does not require any quoting.
 
136
 * LIST and NLST can take optional argument d (the optional part shown in
 
137
 * square brakets which are not elements of either command).
 
138
 *
 
139
 * Current implementation forbids file names to contain '\0', '\n', or '\r'.
 
140
 *
 
141
 * Normally, FTP connection operates in the READ mode:  commands are written
 
142
 * and responses are read.  In this mode the connection consumes any command,
 
143
 * but those invalid, unrecognized, or rejected by the server will cause
 
144
 * CONN_Status(eIO_Write) to return non-eIO_Success.  Note that since normally
 
145
 * CONN_Write() returns eIO_Success when at least one byte of data has been
 
146
 * consumed, its return code is basically useless to distinguish the command
 
147
 * completion status.  Instead of terminating commands with '\n', CONN_Flush()
 
148
 * can be used, and its return code will be the true status of how the command
 
149
 * was done.  Alternatively, CONN_Wait(eIO_Read) can cause a similar effect,
 
150
 * and finally, a read from FTP connection that operates in READ mode causes a
 
151
 * pending command to be executed (even if the connection was created untied,
 
152
 * the additional flushing is done internally).
 
153
 *
 
154
 * When a RETR command gets executed, the following reads from the connection
 
155
 * will retrieve the contents of the file (until eIO_Closed).  If the
 
156
 * connection returns eIO_Closed right away, it means that either the file does
 
157
 * not exist, is not a file but a directory, or is empty.  The first two cases
 
158
 * would cause CONN_Status(eIO_Write) to return a code different from
 
159
 * eIO_Success; and eIO_Success would only result in the case of an empty file.
 
160
 *
 
161
 * File size will be checked by the connector to see whether the download (or
 
162
 * upload, see below) was complete (sometimes, the information returned from
 
163
 * the server does not permit doing this check).  Any mismatch will result in
 
164
 * an error different from eIO_Closed.  (For buggy / noisy FTP servers, the
 
165
 * size checks can be suppressed in the connector flags.)
 
166
 *
 
167
 * During file download, any command (legitimate or not) written to connection
 
168
 * and triggered for execution will abort the data transfer (cause a warning
 
169
 * logged, and connection must still be manually drained until eIO_Closed), but
 
170
 * if an output is expected from such a command, it cannot be distinguished
 
171
 * from the remnants of the file data -- so such a method is not very robust.
 
172
 * There is a special NOOP command that can be written to abort the transfer:
 
173
 * it produces no output (just inserts eIO_Closed in data), and for it is to be
 
174
 * a legitimate command, it usually results in eIO_Success when inquired for
 
175
 * write status (the result may be different on a rare occasion if the server
 
176
 * has chosen to close control connection, for example).  Still, to be usable
 
177
 * again the connection must be drained out until eIO_Closed is received
 
178
 * by reading.
 
179
 *
 
180
 * Connection is switched to SEND mode upon either APPE or STOR is executed.
 
181
 * If they are successful (CONN_Status(eIO_Write) reports eIO_Success), then
 
182
 * any following writes will send the data to the file being uploaded (while
 
183
 * the file is being uploaded, CONN_Status(eIO_Write) will report the status of
 
184
 * last write operation to the file).  Should an error occur eIO_Closed would
 
185
 * result and the connection would not accept any more writes until it is read.
 
186
 * Similarly, when the upload is about to finish, the connection must be read
 
187
 * to finalize the transfer.  The result of the read will be a string
 
188
 * representing the size of the uploaded file data (or an empty read in case
 
189
 * of an upload error) as a sequence of decimal digits.  Once all digits are
 
190
 * extracted (eIO_Closed seen) the connection returns to READ mode.
 
191
 *
 
192
 * Unfinalized uploads (such as when a connection gets closed before the final
 
193
 * read) get reported to the log, and also cause CONN_Close() to return an
 
194
 * error.  Note that unlike file download (which occurs in READ mode), it is
 
195
 * impossible to abort an upload by writing any FTP commands (since writing in
 
196
 * SEND mode goes to file), but it is reading that will do the cancel.  So if
 
197
 * a connection is in undetermined state, the recovery would be to do a small
 
198
 * quick read (e.g. for just 1 byte with zero timeout), then write the "NOOP"
 
199
 * command and cause an execution (e.g. writing "NOOP\n" does that), then
 
200
 * drain the connection by reading again until eIO_Closed.
 
201
 *
 
202
 * Note that for commands, which return text codes, it is allowed not to read
 
203
 * the codes out, but rely solely on CONN_Status() responses.  Any pending
 
204
 * (unread) result of the previous command gets discarded when a new command
 
205
 * gets executed (i.e. command accumulation in the internal buffer does not
 
206
 * cause the pending result to be discarded, it is connection flushing, as
 
207
 * with '\n', CONN_Flush(), etc).  (Same happens with results of the commands
 
208
 * returning non-code information, but reading it out is supposed to be the
 
209
 * very purpose of issuing such commands, and hence, is not mentioned above.)
 
210
 *
 
211
 * The supplement mode of CONN API can make use of FTP connection much easier:
 
212
 * instead of checking for CONN_Status(), direct return codes of read/write
 
213
 * operations can be used.  Care must be taken to interpret eIO_Closed that may
 
214
 * result from read operations (such as when extracting the code that is
 
215
 * immediately followed by the response boundary denoted as eIO_Closed).
 
216
 *
 
217
 * To make the code robust, it is always advised to first process the actual
 
218
 * byte count reported from CONN I/O and only then to analyze the return code.
 
219
 */
 
220
 
 
221
/*
 
222
 * Even though many FTP server implementations provide SIZE command these days,
 
223
 * some FTPDs still lack this feature and can post the file size only when the
 
224
 * actual download starts.  For them, and for connections that do not want to
 
225
 * get the size inserted into the data stream (which is the default behavior
 
226
 * upon a successful SIZE command), the following callback is provided as an
 
227
 * alternative solution.
 
228
 * The callback gets activated when downloads start, and also upon successful
 
229
 * SIZE commands (without causing the file size to appear in the connection
 
230
 * data as it usually would otherwise) but the latter is only if
 
231
 * fFTP_NotifySize has been set in the "flag" parameter of FTP connector
 
232
 * constructors (below).
 
233
 * Each time the size gets passed to the callback as a '\0'-terminated
 
234
 * character string.
 
235
 * The callback remains effective for the entire lifetime of the connector.
 
236
 * As the first argument, the callback also gets a copy of the FTP command
 
237
 * that triggered it, and for compatibility with future extensions, the user
 
238
 * code is expected to check which command it is processing, before proceeding
 
239
 * with the "arg" parameter (thus skipping unexpected commands, and returning
 
240
 * eIO_Success).  Return code non-eIO_Success causes the command terminate
 
241
 * with an error, with the code returned "as-is" from a CONN call.
 
242
 *
 
243
 * NOTE:  With restarted data retrievals (REST) the size reported by the server
 
244
 * in response to transfer initiation can be either the true size of the data
 
245
 * to be received or the entire size of the original file (without the restart
 
246
 * offset taken into account), and the latter should be considered as a bug.
 
247
 */
 
248
typedef EIO_Status (*FFTP_Callback)(void* data,
 
249
                                    const char* cmd, const char* arg);
 
250
typedef struct {
 
251
    FFTP_Callback     func;   /* to call upon certain FTP commands           */
 
252
    void*             data;   /* to supply as a first callback parameter     */
 
253
} SFTP_Callback;
 
254
 
 
255
 
 
256
/* Create new CONNECTOR structure to handle FTP transfers,
 
257
 * both download and upload.  Return NULL on error.
 
258
 */
 
259
extern NCBI_XCONNECT_EXPORT CONNECTOR FTP_CreateConnectorSimple
 
260
(const char*          host,   /* hostname, required                          */
 
261
 unsigned short       port,   /* port #, 21 [standard] if 0 passed here      */
 
262
 const char*          user,   /* username, "ftp" [==anonymous] by default    */
 
263
 const char*          pass,   /* password, "none" by default                 */
 
264
 const char*          path,   /* initial directory to "chdir" to on server   */
 
265
 TFTP_Flags           flag,   /* mostly for logging socket data [optional]   */
 
266
 const SFTP_Callback* cmcb    /* command callback [optional]                 */
 
267
);
 
268
 
 
269
 
 
270
/* Same as above but use fields provided by the connection structure */
73
271
extern NCBI_XCONNECT_EXPORT CONNECTOR FTP_CreateConnector
74
 
(const char*    host,     /* hostname, required                             */
75
 
 unsigned short port,     /* port #, 21 [standard] if 0 passed here         */
76
 
 const char*    user,     /* username, "ftp" [==anonymous] by default       */
77
 
 const char*    pass,     /* password, "none" by default                    */
78
 
 const char*    path,     /* initial directory to chdir to on open          */
79
 
 TFCDC_Flags    flag      /* mostly for logging socket data [optional]      */
 
272
(const SConnNetInfo*  info,   /* all connection params including HTTP proxy  */
 
273
 TFTP_Flags           flag,   /* mostly for logging socket data [optional]   */
 
274
 const SFTP_Callback* cmcb    /* command callback [optional]                 */
80
275
);
81
276
 
82
277
 
83
 
#ifndef NCBI_DEPRECATED
84
 
#  define NCBI_FTP_CONNECTOR_DEPRECATED
85
 
#else
86
 
#  define NCBI_FTP_CONNECTOR_DEPRECATED NCBI_DEPRECATED
87
 
#endif
88
 
 
89
278
/* Same as above:  do not use for the obsolete naming */
90
279
NCBI_FTP_CONNECTOR_DEPRECATED
91
280
extern NCBI_XCONNECT_EXPORT CONNECTOR FTP_CreateDownloadConnector
92
281
(const char* host, unsigned short port, const char* user,
93
 
 const char* pass, const char*    path, TFCDC_Flags flag);
 
282
 const char* pass, const char*    path, TFTP_Flags  flag);
94
283
 
95
284
 
96
285
#ifdef __cplusplus