Improved comments

git-svn-id: svn://svn.code.sf.net/p/nuttx/code/trunk@3658 42af7a65-404d-4744-a932-0658087f49c3

9 files changed, 252 insertions, 44 deletions

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;
 }