---------------------
PatchSet 5341 
Date: 2007/08/15 07:12:34
Author: amosjeffries
Branch: docs
Tag: (none) 
Log:
Link FTP protocol details as a module.

Members: 
	doc/Programming-Guide/Groups.dox:1.1.2.11->1.1.2.12 
	src/ftp.cc:1.73.2.5->1.73.2.6 
	src/protos.h:1.82.4.3->1.82.4.4 

Index: squid3/doc/Programming-Guide/Groups.dox
===================================================================
RCS file: /cvsroot/squid-sf//squid3/doc/Programming-Guide/Attic/Groups.dox,v
retrieving revision 1.1.2.11
retrieving revision 1.1.2.12
diff -u -r1.1.2.11 -r1.1.2.12
--- squid3/doc/Programming-Guide/Groups.dox	15 Aug 2007 02:32:56 -0000	1.1.2.11
+++ squid3/doc/Programming-Guide/Groups.dox	15 Aug 2007 07:12:34 -0000	1.1.2.12
@@ -76,9 +76,8 @@
  */
 
 /**
- \defgroup ServerProtocolFTP FTP
+ \defgroup ServerProtocolFTPAPI Server-Side FTP API
  \ingroup ServerProtocol
- \todo Write Documentation about FTP
  */
 
 /**
Index: squid3/src/ftp.cc
===================================================================
RCS file: /cvsroot/squid-sf//squid3/src/ftp.cc,v
retrieving revision 1.73.2.5
retrieving revision 1.73.2.6
diff -u -r1.73.2.5 -r1.73.2.6
--- squid3/src/ftp.cc	15 Aug 2007 01:00:04 -0000	1.73.2.5
+++ squid3/src/ftp.cc	15 Aug 2007 07:12:34 -0000	1.73.2.6
@@ -1,5 +1,5 @@
 /*
- * $Id: ftp.cc,v 1.73.2.5 2007/08/15 01:00:04 amosjeffries Exp $
+ * $Id: ftp.cc,v 1.73.2.6 2007/08/15 07:12:34 amosjeffries Exp $
  *
  * DEBUG: section 9     File Transfer Protocol (FTP)
  * AUTHOR: Harvest Derived
@@ -54,9 +54,18 @@
 #include "SquidTime.h"
 #include "URLScheme.h"
 
+/**
+ \defgroup ServerProtocolFTPInternal Server-Side FTP Internals
+ \ingroup ServerProtocolFTPAPI
+ */
+
+/// \ingroup ServerProtocolFTPInternal
 static const char *const crlf = "\r\n";
+
+/// \ingroup ServerProtocolFTPInternal
 static char cbuf[1024];
 
+/// \ingroup ServerProtocolFTPInternal
 typedef enum {
     BEGIN,
     SENT_USER,
@@ -78,6 +87,7 @@
     SENT_MKDIR
 } ftp_state_t;
 
+/// \ingroup ServerProtocolFTPInternal
 struct _ftp_flags
 {
     bool isdir;
@@ -103,8 +113,11 @@
 };
 
 class FtpStateData;
+
+/// \ingroup ServerProtocolFTPInternal
 typedef void (FTPSM) (FtpStateData *);
 
+/// \ingroup ServerProtocolFTPInternal
 class FtpStateData : public ServerStateData
 {
 
@@ -243,6 +256,7 @@
     cbdataFree(t);
 }
 
+/// \ingroup ServerProtocolFTPInternal
 typedef struct
 {
     char type;
@@ -252,10 +266,12 @@
     char *showname;
     char *link;
 }
-
 ftpListParts;
 
+/// \ingroup ServerProtocolFTPInternal
 #define FTP_LOGIN_ESCAPED 1
+
+/// \ingroup ServerProtocolFTPInternal
 #define FTP_LOGIN_NOT_ESCAPED 0
 
 /*
@@ -331,6 +347,7 @@
 Quit			-
 ************************************************/
 
+/// \ingroup ServerProtocolFTPInternal
 FTPSM *FTP_SM_FUNCS[] =
     {
         ftpReadWelcome,		/* BEGIN */
@@ -598,12 +615,14 @@
     printfReplyBody("</ADDRESS></BODY></HTML>\n");
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static const char *Month[] =
     {
         "Jan", "Feb", "Mar", "Apr", "May", "Jun",
         "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"
     };
 
+/// \ingroup ServerProtocolFTPInternal
 static int
 is_month(const char *buf)
 {
@@ -616,7 +635,7 @@
     return 0;
 }
 
-
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpListPartsFree(ftpListParts ** parts)
 {
@@ -627,10 +646,11 @@
     safe_free(*parts);
 }
 
+/// \ingroup ServerProtocolFTPInternal
 #define MAX_TOKENS 64
 
+/// \ingroup ServerProtocolFTPInternal
 static ftpListParts *
-
 ftpListParseParts(const char *buf, struct _ftp_flags flags)
 {
     ftpListParts *p = NULL;
@@ -863,6 +883,7 @@
     return p;
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static const char *
 dots_fill(size_t len)
 {
@@ -1355,11 +1376,9 @@
     maybeReadVirginBody();
 }
 
-/*
- * ftpCheckAuth
- *
- * Return 1 if we have everything needed to complete this request.
- * Return 0 if something is missing.
+/**
+ \retval 1	if we have everything needed to complete this request.
+ \retval 0	if something is missing.
  */
 int
 FtpStateData::checkAuth(const HttpHeader * req_hdr)
@@ -1472,6 +1491,7 @@
     base_href.append("/");
 }
 
+/// \ingroup ServerProtocolFTPAPI
 void
 ftpStart(FwdState * fwd)
 {
@@ -1520,6 +1540,7 @@
 
 /* ====================================================================== */
 
+/// \ingroup ServerProtocolFTPInternal
 static char *
 escapeIAC(const char *buf)
 {
@@ -1684,7 +1705,7 @@
     return head;
 }
 
-/*
+/**
  * DPW 2007-04-23
  * Looks like there are no longer anymore callers that set
  * buffered_ok=1.  Perhaps it can be removed at some point.
@@ -1823,6 +1844,7 @@
 
 /* ====================================================================== */
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpReadWelcome(FtpStateData * ftpState)
 {
@@ -1852,6 +1874,7 @@
     }
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpSendUser(FtpStateData * ftpState)
 {
@@ -1871,6 +1894,7 @@
     ftpState->state = SENT_USER;
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpReadUser(FtpStateData * ftpState)
 {
@@ -1886,6 +1910,7 @@
     }
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpSendPass(FtpStateData * ftpState)
 {
@@ -1898,6 +1923,7 @@
     ftpState->state = SENT_PASS;
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpReadPass(FtpStateData * ftpState)
 {
@@ -1911,6 +1937,7 @@
     }
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpSendType(FtpStateData * ftpState)
 {
@@ -1963,6 +1990,7 @@
     ftpState->state = SENT_TYPE;
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpReadType(FtpStateData * ftpState)
 {
@@ -2001,6 +2029,7 @@
     }
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpTraverseDirectory(FtpStateData * ftpState)
 {
@@ -2038,6 +2067,7 @@
     }
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpSendCwd(FtpStateData * ftpState)
 {
@@ -2064,6 +2094,7 @@
     ftpState->state = SENT_CWD;
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpReadCwd(FtpStateData * ftpState)
 {
@@ -2094,6 +2125,7 @@
     }
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpSendMkdir(FtpStateData * ftpState)
 {
@@ -2110,6 +2142,7 @@
     ftpState->state = SENT_MKDIR;
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpReadMkdir(FtpStateData * ftpState)
 {
@@ -2131,6 +2164,7 @@
         ftpSendReply(ftpState);
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpGetFile(FtpStateData * ftpState)
 {
@@ -2139,6 +2173,7 @@
     ftpSendMdtm(ftpState);
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpListDir(FtpStateData * ftpState)
 {
@@ -2151,6 +2186,7 @@
     ftpSendPasv(ftpState);
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpSendMdtm(FtpStateData * ftpState)
 {
@@ -2164,6 +2200,7 @@
     ftpState->state = SENT_MDTM;
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpReadMdtm(FtpStateData * ftpState)
 {
@@ -2181,6 +2218,7 @@
     ftpSendSize(ftpState);
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpSendSize(FtpStateData * ftpState)
 {
@@ -2202,6 +2240,7 @@
         ftpSendPasv(ftpState);
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpReadSize(FtpStateData * ftpState)
 {
@@ -2226,6 +2265,7 @@
     ftpSendPasv(ftpState);
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpSendPasv(FtpStateData * ftpState)
 {
@@ -2330,6 +2370,7 @@
     processReplyBody(); 
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpReadPasv(FtpStateData * ftpState)
 {
@@ -2435,6 +2476,7 @@
     ftpRestOrList(ftpState);
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static int
 ftpOpenListenSocket(FtpStateData * ftpState, int fallback)
 {
@@ -2498,6 +2540,7 @@
     return fd;
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpSendPort(FtpStateData * ftpState)
 {
@@ -2534,6 +2577,7 @@
     ftpState->state = SENT_PORT;
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpReadPort(FtpStateData * ftpState)
 {
@@ -2549,7 +2593,11 @@
     ftpRestOrList(ftpState);
 }
 
-/* "read" handler to accept data connection */
+/**
+ \ingroup ServerProtocolFTPInternal
+ *
+ * "read" handler to accept data connection
+*/
 static void
 ftpAcceptDataConnection(int fd, int newfd, ConnectionDetail *details,
                         comm_err_t flag, int xerrno, void *data)
@@ -2610,6 +2658,7 @@
     FTP_SM_FUNCS[ftpState->state] (ftpState);
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpRestOrList(FtpStateData * ftpState)
 {
@@ -2634,6 +2683,7 @@
         ftpSendRetr(ftpState);
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpSendStor(FtpStateData * ftpState)
 {
@@ -2657,6 +2707,8 @@
     }
 }
 
+/// \ingroup ServerProtocolFTPInternal
+/// \deprecated use ftpState->readStor() instead.
 static void
 ftpReadStor(FtpStateData * ftpState)
 {
@@ -2699,6 +2751,7 @@
     }
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpSendRest(FtpStateData * ftpState)
 {
@@ -2738,6 +2791,7 @@
     return 1;
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpReadRest(FtpStateData * ftpState)
 {
@@ -2757,6 +2811,7 @@
     }
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpSendList(FtpStateData * ftpState)
 {
@@ -2774,6 +2829,7 @@
     ftpState->state = SENT_LIST;
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpSendNlst(FtpStateData * ftpState)
 {
@@ -2793,6 +2849,7 @@
     ftpState->state = SENT_NLST;
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpReadList(FtpStateData * ftpState)
 {
@@ -2828,6 +2885,7 @@
     }
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpSendRetr(FtpStateData * ftpState)
 {
@@ -2841,6 +2899,7 @@
     ftpState->state = SENT_RETR;
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpReadRetr(FtpStateData * ftpState)
 {
@@ -2880,6 +2939,7 @@
     }
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpReadTransferDone(FtpStateData * ftpState)
 {
@@ -2910,7 +2970,9 @@
     failed(ERR_READ_ERROR, 0);
 }
 
-/* This will be called when the put write is completed */
+/**
+ * This will be called when the put write is completed
+ */
 void
 FtpStateData::sentRequestBody(int fd, size_t size, comm_err_t errflag)
 {
@@ -2919,6 +2981,7 @@
     ServerStateData::sentRequestBody(fd, size, errflag);
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpWriteTransferDone(FtpStateData * ftpState)
 {
@@ -2935,6 +2998,7 @@
     ftpSendReply(ftpState);
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpSendQuit(FtpStateData * ftpState)
 {
@@ -2947,13 +3011,15 @@
     ftpState->state = SENT_QUIT;
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpReadQuit(FtpStateData * ftpState)
 {
-    /* XXX should this just be a case of abortTransaction? */
+    /** \todo XXX should this just be a case of abortTransaction? */
     ftpState->serverComplete();
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpTrySlashHack(FtpStateData * ftpState)
 {
@@ -2977,7 +3043,9 @@
     ftpGetFile(ftpState);
 }
 
-/* Forget hack status. Next error is shown to the user */
+/**
+ * Forget hack status. Next error is shown to the user
+ */
 void
 FtpStateData::unhack()
 {
@@ -3009,6 +3077,7 @@
     nextState(this);
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpFail(FtpStateData *ftpState)
 {
@@ -3130,6 +3199,7 @@
     fwd->fail(err);
 }
 
+/// \ingroup ServerProtocolFTPInternal
 static void
 ftpSendReply(FtpStateData * ftpState)
 {
@@ -3289,6 +3359,10 @@
     return newrep;
 }
 
+/**
+ \ingroup ServerProtocolFTPAPI
+ \todo Should be a URL class API call.
+ */
 char *
 ftpUrlWith2f(const HttpRequest * request)
 {
@@ -3340,7 +3414,7 @@
     writeReplyBody(buf, strlen(buf));
 }
 
-/*
+/**
  * Call this when there is data from the origin server
  * which should be sent to either StoreEntry, or to ICAP...
  */
@@ -3351,7 +3425,9 @@
     addVirginReplyBody(data, len);
 }
 
-// called after we wrote the last byte of the request body
+/**
+ * called after we wrote the last byte of the request body
+ */
 void
 FtpStateData::doneSendingRequestBody()
 {
@@ -3359,9 +3435,12 @@
     ftpWriteTransferDone(this);
 }
 
-// a hack to ensure we do not double-complete on the forward entry.
-// TODO: FtpStateData logic should probably be rewritten to avoid 
-// double-completion or FwdState should be rewritten to allow it.
+/**
+ * A hack to ensure we do not double-complete on the forward entry.
+ *
+ \todo FtpStateData logic should probably be rewritten to avoid 
+ *	double-completion or FwdState should be rewritten to allow it.
+ */
 void
 FtpStateData::completeForwarding()
 {
@@ -3376,7 +3455,9 @@
     ServerStateData::completeForwarding();
 }
 
-// Close the FTP server connection(s). Used by serverComplete().
+/**
+ * Close the FTP server connection(s). Used by serverComplete().
+ */
 void
 FtpStateData::closeServer()
 {
@@ -3395,13 +3476,24 @@
     }
 }
 
-// Did we close all FTP server connection(s)?
+/**
+ * Did we close all FTP server connection(s)?
+ *
+ \retval true	Both server control and data channels are closed.
+ \retval false	Either control channel or data is still active.
+ */
 bool
 FtpStateData::doneWithServer() const
 {
     return ctrl.fd < 0 && data.fd < 0;
 }
 
+/**
+ * Have we lost the FTP server control channel?
+ *
+ \retval true	The server control channel is available.
+ \retval false	The server control channel is not available.
+ */
 bool
 FtpStateData::haveControlChannel(const char *caller_name) const
 {
@@ -3412,9 +3504,12 @@
     return false;
 }
 
-// Quickly abort the transaction
-// TODO: destruction should be sufficient as the destructor should cleanup,
-// including canceling close handlers
+/**
+ * Quickly abort the transaction
+ *
+ \todo destruction should be sufficient as the destructor should cleanup,
+ *	including canceling close handlers
+ */
 void
 FtpStateData::abortTransaction(const char *reason)
 {
Index: squid3/src/protos.h
===================================================================
RCS file: /cvsroot/squid-sf//squid3/src/protos.h,v
retrieving revision 1.82.4.3
retrieving revision 1.82.4.4
diff -u -r1.82.4.3 -r1.82.4.4
--- squid3/src/protos.h	15 Aug 2007 01:00:04 -0000	1.82.4.3
+++ squid3/src/protos.h	15 Aug 2007 07:12:34 -0000	1.82.4.4
@@ -1,6 +1,6 @@
 
 /*
- * $Id: protos.h,v 1.82.4.3 2007/08/15 01:00:04 amosjeffries Exp $
+ * $Id: protos.h,v 1.82.4.4 2007/08/15 07:12:34 amosjeffries Exp $
  *
  *
  * SQUID Web Proxy Cache          http://www.squid-cache.org/
@@ -180,9 +180,8 @@
 class FwdState;
 
 /**
- \defgroup ServerProtocolGopherAPI Server-Side Gopher API
+ \defgroup ServerProtocolGopherAPI Server-Side FTP API
  \ingroup ServerProtocol
- \todo Squid3 re-code: Gopher should have its own API header file.
  */
 
 /// \ingroup ServerProtocolFTPAPI
@@ -191,10 +190,10 @@
 /// \ingroup ServerProtocolFTPAPI
 SQUIDCEXTERN char *ftpUrlWith2f(const HttpRequest *);
 
+
 /**
  \defgroup ServerProtocolGopherAPI Server-Side Gopher API
  \ingroup ServerProtocol
- \todo Squid3 re-code: Gopher should have its own API header file.
  */
 
 /// \ingroup ServerProtocolGopherAPI
@@ -207,12 +206,12 @@
 /**
  \defgroup ServerProtocolWhoisAPI Server-Side WHOIS API
  \ingroup ServerProtocol
- \todo Squid3 re-code: WHOIS should have its own API header file.
  */
 
 /// \ingroup ServerProtocolWhoisAPI
 SQUIDCEXTERN void whoisStart(FwdState *);
 
+
 /* http.c */
 SQUIDCEXTERN int httpCachable(method_t);
 SQUIDCEXTERN void httpStart(FwdState *);