From 6f39c643ac7af0880f49f7673307053db11218e9 Mon Sep 17 00:00:00 2001 From: patacongo Date: Thu, 2 Jun 2011 01:14:12 +0000 Subject: Improved comments git-svn-id: svn://svn.code.sf.net/p/nuttx/code/trunk@3658 42af7a65-404d-4744-a932-0658087f49c3 --- apps/netutils/ftpc/ftpc_getfile.c | 22 +++++++- apps/netutils/ftpc/ftpc_listdir.c | 31 +++++++++- apps/netutils/ftpc/ftpc_login.c | 40 ++++++++++++- apps/netutils/ftpc/ftpc_mkdir.c | 12 ++++ apps/netutils/ftpc/ftpc_putfile.c | 113 ++++++++++++++++++++++++++----------- apps/netutils/ftpc/ftpc_rename.c | 30 ++++++++++ apps/netutils/ftpc/ftpc_rmdir.c | 11 ++++ apps/netutils/ftpc/ftpc_transfer.c | 26 +++++++-- apps/netutils/ftpc/ftpc_unlink.c | 11 ++++ 9 files changed, 252 insertions(+), 44 deletions(-) (limited to 'apps/netutils') diff --git a/apps/netutils/ftpc/ftpc_getfile.c b/apps/netutils/ftpc/ftpc_getfile.c index 095bf2414..039643d0e 100644 --- a/apps/netutils/ftpc/ftpc_getfile.c +++ b/apps/netutils/ftpc/ftpc_getfile.c @@ -120,7 +120,27 @@ static int ftpc_recvinit(struct ftpc_session_s *session, FAR const char *path, session->rstrsize = offset; } - /* Send the RETR (Retrieve a remote file) command */ + /* Send the RETR (Retrieve a remote file) command. Normally the server + * responds with a mark using code 150: + * + * - "150 File status okay; about to open data connection" + * + * It then stops accepting new connections, attempts to send the contents + * of the file over the data connection, and closes the data connection. + * Finally it either accepts the RETR request with: + * + * - "226 Closing data connection" if the entire file was successfully + * written to the server's TCP buffers + * + * Or rejects the RETR request with: + * + * - "425 Can't open data connection" if no TCP connection was established + * - "426 Connection closed; transfer aborted" if the TCP connection was + * established but then broken by the client or by network failure + * - "451 Requested action aborted: local error in processing" or + * "551 Requested action aborted: page type unknown" if the server had + * trouble reading the file from disk. + */ ret = ftpc_cmd(session, "RETR %s", path); if (ret < 0) diff --git a/apps/netutils/ftpc/ftpc_listdir.c b/apps/netutils/ftpc/ftpc_listdir.c index e58b874e7..20653799c 100644 --- a/apps/netutils/ftpc/ftpc_listdir.c +++ b/apps/netutils/ftpc/ftpc_listdir.c @@ -256,7 +256,15 @@ static int ftpc_recvdir(FAR struct ftpc_session_s *session, return ERROR; } - /* Send the "NLST" command */ + /* Send the "NLST" command. Normally the server responds with a mark + * using code 150: + * + * - "150 File status okay; about to open data connection" + * + * It then stops accepting new connections, attempts to + * send the contents of the directory over the data connection, and + * closes the data connection. + */ ret = ftpc_cmd(session, "NLST"); if (ret != OK) @@ -273,7 +281,7 @@ static int ftpc_recvdir(FAR struct ftpc_session_s *session, return ERROR; } - /* Receive the NLST response */ + /* Receive the NLST directory list */ ret = ftpc_recvtext(session, session->data.instream, outstream); ftpc_sockclose(&session->data); @@ -282,7 +290,24 @@ static int ftpc_recvdir(FAR struct ftpc_session_s *session, return ERROR; } - /* Get the server reply */ + /* Get the server reply. After closing the data connection, the should + * accept the request with: + * + * - "226 Closing data connection" if the entire directory was + * successfully transmitted; + * + * Or reject it with: + * + * - "425 Can't open data connection" if no TCP connection was established + * - "426 - Connection closed; transfer aborted" if the TCP connection was + * established but then broken by the client or by network failure + * - "451 - Requested action aborted: local error in processing" if the + * server had trouble reading the directory from disk. + * + * The server may reject the LIST or NLST request (with code 450 or 550) + * without first responding with a mark. In this case the server does not + * touch the data connection. + */ fptc_getreply(session); return OK; diff --git a/apps/netutils/ftpc/ftpc_login.c b/apps/netutils/ftpc/ftpc_login.c index df12c0543..4fa8171da 100644 --- a/apps/netutils/ftpc/ftpc_login.c +++ b/apps/netutils/ftpc/ftpc_login.c @@ -147,7 +147,21 @@ int ftpc_relogin(FAR struct ftpc_session_s *session) int err; int ret; - /* Log into the server */ + /* Log into the server. First send the USER command. The server may accept + * USER with: + * + * - "230 User logged in, proceed" meaning that the client has permission to + * access files under that username + * - "331 "User name okay, need password" or "332 Need account for login" + * meaning that permission might be granted after a PASS request. + * + * Or the server may reject USER with: + * + * - "530 Not logged in" meaning that the username is unacceptable. + * + * In practice, the server does not check the username until after a PASS + * request + */ FTPC_CLR_LOGGEDIN(session); ret = ftpc_cmd(session, "USER %s", session->uname); @@ -157,6 +171,21 @@ int ftpc_relogin(FAR struct ftpc_session_s *session) return ERROR; } + /* Send the PASS command with the passed. The server may accept PASS with: + * + * - "230 User logged in, proceed" meaning that the client has permission to + * access files under that username + * - "202 Command not implemented, superfluous at this site" meaning that + * permission was already granted in response to USER + * - "332 Need account for login" meaning that permission might be granted + * after an ACCT request. + * + * The server may reject PASS with: + * + * - "503 Bad sequence of commands" if the previous request was not USER + * - "530 - Not logged in" if this username and password are unacceptable. + */ + ret = ftpc_cmd(session, "PASS %s", session->pwd); if (ret != OK) { @@ -164,10 +193,19 @@ int ftpc_relogin(FAR struct ftpc_session_s *session) return ret; } + /* We are logged in.. the current working directory on login is our "home" + * directory. + */ + FTPC_SET_LOGGEDIN(session); session->homedir = ftpc_pwd((SESSION)session); session->curdir = strdup(session->homedir); session->prevdir = strdup(session->homedir); + + /* If the user has requested a special start up directory, then change to + * that directory now. + */ + if (session->initdir) { ftpc_chdir((SESSION)session, session->initdir); diff --git a/apps/netutils/ftpc/ftpc_mkdir.c b/apps/netutils/ftpc/ftpc_mkdir.c index d11466112..0662f2cbc 100644 --- a/apps/netutils/ftpc/ftpc_mkdir.c +++ b/apps/netutils/ftpc/ftpc_mkdir.c @@ -87,6 +87,18 @@ int ftpc_mkdir(SESSION handle, FAR const char *path) ptr = strdup(path); ftpc_stripslash(ptr); + /* Send the MKD request. The MKD request asks the server to create a new + * directory. The server accepts the MKD with either: + * + * - "257 PATHNAME created" that includes the pathname of the directory + * - "250 - Requested file action okay, completed" if the directory was + * successfully created. + * + * The server reject MKD with: + * + * - "550 Requested action not taken" if the creation failed. + */ + ret = ftpc_cmd(session, "MKD %s", ptr); free(ptr); return ret; diff --git a/apps/netutils/ftpc/ftpc_putfile.c b/apps/netutils/ftpc/ftpc_putfile.c index ec70e58df..edee42e41 100644 --- a/apps/netutils/ftpc/ftpc_putfile.c +++ b/apps/netutils/ftpc/ftpc_putfile.c @@ -208,6 +208,8 @@ static int ftpc_sendfile(struct ftpc_session_s *session, const char *path, FILE *stream, uint8_t how, uint8_t xfrmode) { long offset = session->offset; + FAR char *str; + int len; int ret; session->offset = 0; @@ -236,6 +238,10 @@ static int ftpc_sendfile(struct ftpc_session_s *session, const char *path, ftpc_xfrmode(session, xfrmode); + /* The REST command sets the start position in the file. Some servers + * allow REST immediately before STOR for binary files. + */ + if (offset > 0) { ret = ftpc_cmd(session, "REST %ld", offset); @@ -243,19 +249,56 @@ static int ftpc_sendfile(struct ftpc_session_s *session, const char *path, session->rstrsize = offset; } - switch(how) + /* Send the file using STOR, STOU, or APPE: + * + * - STOR request asks the server to receive the contents of a file from + * the data connection already established by the client. + * - APPE is just like STOR except that, if the file already exists, the + * server appends the client's data to the file. + * - STOU is just like STOR except that it asks the server to create a + * file under a new pathname selected by the server. If the server + * accepts STOU, it provides the pathname in a human-readable format in + * the text of its response. + */ + + switch (how) { case FTPC_PUT_UNIQUE: - ret = ftpc_cmd(session, "STOU %s", path); + { + ret = ftpc_cmd(session, "STOU %s", path); - /* Check for "502 Command not implemented" */ + /* Check for "502 Command not implemented" */ - if (session->code == 502) - { - /* The host does not support the STOU command */ + if (session->code == 502) + { + /* The host does not support the STOU command */ - FTPC_CLR_STOU(session); - } + FTPC_CLR_STOU(session); + return ERROR; + } + + /* Get the remote filename from the response */ + + str = strstr(session->reply, " for "); + if (str) + { + str += 5; + len = strlen(str); + if (len) + { + free(session->lname); + if (*str == '\'') + { + session->lname = strndup(str+1, len-3); + } + else + { + session->lname = strndup(str, len-1); + nvdbg("Unique filename is: %s\n", session->lname); + } + } + } + } break; case FTPC_PUT_APPEND: @@ -268,32 +311,34 @@ static int ftpc_sendfile(struct ftpc_session_s *session, const char *path, break; } - if (how == FTPC_PUT_UNIQUE) - { - /* Determine the remote filename */ - - char *str = strstr(session->reply, " for "); - if (str) - { - int len; - - str += 5; - len = strlen(str); - if (len) - { - free(session->lname); - if (*str == '\'') - { - session->lname = strndup(str+1, len-3); - } - else - { - session->lname = strndup(str, len-1); - nvdbg("parsed unique filename as '%s'\n", session->lname); - } - } - } - } + /* If the server is willing to create a new file under that name, or + * replace an existing file under that name, it responds with a mark + * using code 150: + * + * - "150 File status okay; about to open data connection" + * + * It then attempts to read the contents of the file from the data + * connection, and closes the data connection. Finally it accepts the STOR + * with: + * + * - "226 Closing data connection" if the entire file was successfully + * received and stored + * + * Or rejects the STOR with: + * + * - "425 Can't open data connection" if no TCP connection was established + * - "426 Connection closed; transfer aborted" if the TCP connection was + * established but then broken by the client or by network failure + * - "451 Requested action aborted: local error in processing", + * "452 - Requested action not taken", or "552 Requested file action + * aborted" if the server had trouble saving the file to disk. + * + * The server may reject the STOR request with: + * + * - "450 Requested file action not taken", "452 - Requested action not + * taken" or "553 Requested action not taken" without first responding + * with a mark. + */ ret = ftpc_sockaccept(&session->data, "w", FTPC_IS_PASSIVE(session)); if (ret != OK) diff --git a/apps/netutils/ftpc/ftpc_rename.c b/apps/netutils/ftpc/ftpc_rename.c index c1a80c289..d14bdf3f3 100644 --- a/apps/netutils/ftpc/ftpc_rename.c +++ b/apps/netutils/ftpc/ftpc_rename.c @@ -87,6 +87,19 @@ int ftpc_rename(SESSION handle, FAR const char *oldname, FAR const char *newname oldcopy = strdup(oldname); ftpc_stripslash(oldcopy); + + /* A RNFR request asks the server to begin renaming a file. A typical + * server accepts RNFR with: + * + * - "350 Requested file action pending further information" if the file + * exists + * + * Or rejects RNFR with: + * + * - "450 Requested file action not taken" + * - "550 Requested action not taken" + */ + ret = ftpc_cmd(session, "RNFR %s", oldcopy); if (ret != OK) { @@ -96,6 +109,23 @@ int ftpc_rename(SESSION handle, FAR const char *oldname, FAR const char *newname newcopy = strdup(newname); ftpc_stripslash(newcopy); + + /* A RNTO request asks the server to finish renaming a file. RNTO must + * come immediately after RNFR; otherwise the server may reject RNTO with: + * + * - "503 Bad sequence of commands" + * + * A typical server accepts RNTO with: + * + * - "250 Requested file action okay, completed" if the file was renamed + * successfully + * + * Or rejects RMD with: + * + * - "550 Requested action not taken" + * - "553 Requested action not taken" + */ + ret = ftpc_cmd(session, "RNTO %s", newcopy); free(oldcopy); diff --git a/apps/netutils/ftpc/ftpc_rmdir.c b/apps/netutils/ftpc/ftpc_rmdir.c index caa50392f..bb86941ae 100644 --- a/apps/netutils/ftpc/ftpc_rmdir.c +++ b/apps/netutils/ftpc/ftpc_rmdir.c @@ -85,6 +85,17 @@ int ftpc_rmdir(SESSION handle, FAR const char *path) ptr = strdup(path); ftpc_stripslash(ptr); + /* An RMD request asks the server to remove a directory. A typical server + * accepts RMD with: + * + * - "250 Requested file action okay, completed" if the directory was + * successfully removed + * + * Or rejects RMD with: + * + * - "550 Requested action not taken" if the removal failed. + */ + ret = ftpc_cmd(session, "RMD %s", ptr); free(ptr); return ret; diff --git a/apps/netutils/ftpc/ftpc_transfer.c b/apps/netutils/ftpc/ftpc_transfer.c index 640e92276..bc0ca8b03 100644 --- a/apps/netutils/ftpc/ftpc_transfer.c +++ b/apps/netutils/ftpc/ftpc_transfer.c @@ -115,7 +115,10 @@ static int ftp_pasvmode(struct ftpc_session_s *session, return ERROR; } - /* Request passive mode */ + /* Request passive mode. The server normally accepts PASV with code 227. + * Its response is a single line showing the IP address of the server and + * the TCP port number where the server is accepting connections. + */ ret = ftpc_cmd(session, "PASV"); if (ret < 0 || !ftpc_connected(session)) @@ -277,12 +280,25 @@ int ftpc_xfrmode(struct ftpc_session_s *session, uint8_t xfrmode) { int ret; + /* Check if we have already selected the requested mode */ + DEBUGASSERT(xfrmode != FTPC_XFRMODE_UNKNOWN); if (session->xfrmode != xfrmode) - { - ret = ftpc_cmd(session, "TYPE %c", xfrmode == FTPC_XFRMODE_ASCII ? 'A' : 'I'); - session->xfrmode = xfrmode; - } + { + /* Send the TYPE request to control the binary flag. Parameters for the + * TYPE request include: + * + * A: Turn the binary flag off. + * A N: Turn the binary flag off. + * I: Turn the binary flag on. + * L 8: Turn the binary flag on. + * + * The server accepts the TYPE request with code 200. + */ + + ret = ftpc_cmd(session, "TYPE %c", xfrmode == FTPC_XFRMODE_ASCII ? 'A' : 'I'); + session->xfrmode = xfrmode; + } return OK; } diff --git a/apps/netutils/ftpc/ftpc_unlink.c b/apps/netutils/ftpc/ftpc_unlink.c index 3a49374de..2af5d4f29 100644 --- a/apps/netutils/ftpc/ftpc_unlink.c +++ b/apps/netutils/ftpc/ftpc_unlink.c @@ -80,6 +80,17 @@ int ftpc_unlink(SESSION handle, FAR const char *path) FAR struct ftpc_session_s *session = (FAR struct ftpc_session_s *)handle; int ret; + /* A DELE request asks the server to remove a regular file. A typical server + * accepts DELE with: + * + * - "250 Requested file action okay, completed" if the file was + * successfully removed + * + * Or rejects RMD with: + * + * - "550 Requested action not taken" f the removal failed. + */ + ret = ftpc_cmd(session, "DELE %s", path); return ret; } -- cgit v1.2.3