home *** CD-ROM | disk | FTP | other *** search
/ Geek Gadgets 1 / ADE-1.bin / ade-dist / ncftp-2.3.0-src.tgz / tar.out / contrib / ncftp / RCmd.c < prev    next >
C/C++ Source or Header  |  1996-09-28  |  19KB  |  739 lines
  1. /* RCmd.c */
  2.  
  3. #include "Sys.h"
  4.  
  5. #include <ctype.h>
  6. #include <setjmp.h>
  7. #include <arpa/telnet.h>
  8. #include "Util.h"
  9. #include "RCmd.h"
  10.  
  11. #include <signal.h>
  12. #include <setjmp.h>
  13.  
  14. #include "Open.h"
  15. #include "Main.h"
  16. #include "Xfer.h"
  17. #include "FTP.h"
  18.  
  19. /* NOTE: There is more commentary at the bottom of this source file. */
  20.  
  21. /* User-settable verbosity level.
  22.  * This isn't really used at the moment.
  23.  */
  24. int gVerbosity = kTerse;
  25.  
  26. int gRemoteMsgs = kAllRmtMsgs;
  27.  
  28. int gNetworkTimeout = kDefaultNetworkTimeout;
  29.  
  30. jmp_buf    gTStrTimeOut;
  31.  
  32. extern FILE *gControlIn, *gControlOut;
  33. extern int gDataSocket, gDoneApplication;
  34. extern int gDebug, gConnected, gTrace;
  35. extern jmp_buf gCmdLoopJmp;
  36. extern int gPreferredDataPortMode, gReadingStartup;
  37. extern int gAttemptingConnection;
  38.  
  39. /* The user can control the level of output printed by the program
  40.  * with this.
  41.  */
  42. int SetVerbose(int newVerbose)
  43. {
  44.     int old;
  45.     
  46.     old = gVerbosity;
  47.     gVerbosity = newVerbose;
  48.     return (old);
  49. }    /* SetVerbose */
  50.  
  51.  
  52.  
  53.  
  54. /* A 'Response' parameter block is simply zeroed to be considered init'ed. */
  55. ResponsePtr InitResponse(void)
  56. {
  57.     ResponsePtr rp;
  58.     
  59.     rp = (ResponsePtr) calloc(SZ(1), sizeof(Response));
  60.     if (rp == NULL)
  61.         OutOfMemory();    /* Won't return. */
  62.     InitLineList(&rp->msg);
  63.     return (rp);
  64. }    /* InitResponse */
  65.  
  66.  
  67.  
  68.  
  69. /* If we don't print it to the screen, we may want to save it to our
  70.  * trace log.
  71.  */
  72. void TraceResponse(ResponsePtr rp)
  73. {
  74.     LinePtr lp;
  75.     
  76.     if (rp != NULL)    {
  77.         lp = rp->msg.first;
  78.         if (lp != NULL) {
  79.             TraceMsg("%3d: %s\n", rp->code, lp->line);
  80.             for (lp = lp->next; lp != NULL; lp = lp->next)
  81.                 TraceMsg("     %s\n", lp->line);
  82.         }
  83.     }
  84. }    /* TraceResponse */
  85.  
  86.  
  87.  
  88.  
  89. /* We print a response, which may be several lines of text. 
  90.  * For old time's sake, we will also print the numeric code preceding
  91.  * the first line, since the old ftp client used to always print the
  92.  * response codes too.
  93.  */
  94. void PrintResponse(ResponsePtr rp)
  95. {
  96.     LinePtr lp;
  97.     longstring buf2;
  98.  
  99.     MultiLineInit();
  100.     if (rp != NULL)    {
  101.         if (gDebug == kDebuggingOff) {
  102.             for (lp = rp->msg.first; lp != NULL; lp = lp->next) {
  103.                 MakeStringPrintable(buf2, (unsigned char *) lp->line, sizeof(buf2));
  104.                 MultiLinePrintF("%s\n", buf2);
  105.             }
  106.         } else {
  107.             lp = rp->msg.first;
  108.             if (lp != NULL) {
  109.                 MakeStringPrintable(buf2, (unsigned char *) lp->line, sizeof(buf2));
  110.                 MultiLinePrintF("%03d: %s\n", rp->code, buf2);
  111.                 for (lp = lp->next; lp != NULL; lp = lp->next) {
  112.                     MakeStringPrintable(buf2, (unsigned char *) lp->line, sizeof(buf2));
  113.                     MultiLinePrintF("     %s\n", buf2);
  114.                 }
  115.             }
  116.         }
  117.     }
  118. }    /* PrintResponse */
  119.  
  120.  
  121.  
  122.  
  123. /* This determines if a response should be printed to the screen, given
  124.  * the current verbosity level, the response code level, or the parameters
  125.  * in the Response block.
  126.  */
  127. void PrintResponseIfNeeded(ResponsePtr rp)
  128. {
  129.     int printIt = 0;
  130.     LinePtr lp;
  131.  
  132.     if ((gDebug == kDebuggingOn) || (gVerbosity == kVerbose)) {
  133.         /* Always print if debugging or in verbose mode. */
  134.         printIt = 1;
  135.     } else if (rp->printMode == kDontPrint) {
  136.         /* Never print if we were explicitly told not to. */
  137.         printIt = 0;
  138.     } else if (rp->printMode == kDoPrint) {
  139.         /* Always print if we were explicitly told to. */
  140.         printIt = 1;
  141.     } else if (gVerbosity == kErrorsOnly) {
  142.         /* Most of the time we want to print error responses. */
  143.         if (rp->codeType == 5)
  144.             printIt = 1;
  145.     } else if (gVerbosity == kTerse) {
  146.         /* Most of the time we want to print error responses. */
  147.         if (rp->codeType >= 4) {
  148.             printIt = 1;
  149.         } else {
  150.             switch (rp->code) {
  151.                 case 250:
  152.                     /* Print 250 lines if they aren't
  153.                      * "250 CWD command successful."
  154.                      */
  155.                     if ((gRemoteMsgs & kNoChdirMsgs) == 0) {
  156.                         printIt = 1;
  157.                         for (lp = rp->msg.first; lp != NULL; ) {
  158.                             if (STRNEQ(lp->line, "CWD command", 11)) {
  159.                                 lp = RemoveLine(&rp->msg, lp);
  160.                                 break;
  161.                             } else {
  162.                                 lp = lp->next;
  163.                             }
  164.                         }
  165.                     }
  166.                     break;
  167.                 case 220:
  168.                     /* But skip the foo FTP server ready line. */
  169.                     if ((gRemoteMsgs & kNoConnectMsg) == 0) {
  170.                         printIt = 1;
  171.                         for (lp = rp->msg.first; lp != NULL; ) {
  172.                             if (strstr(lp->line, "ready.") != NULL) {
  173.                                 lp = RemoveLine(&rp->msg, lp);
  174.                                 break;
  175.                             } else {
  176.                                 lp = lp->next;
  177.                             }
  178.                         }
  179.                     }
  180.                     break;
  181.  
  182.                 case 230:    /* User logged in, proceed. */
  183.                     if ((gRemoteMsgs & kNoConnectMsg) == 0) {
  184.                         /* I'll count 230 as a connect message. */
  185.                         printIt = 1;
  186.                     }
  187.                     break;
  188.  
  189.                 case 214:    /* Help message. */
  190.                 case 331:    /* Enter password. */
  191.                     printIt = 1;
  192.                     break;
  193.             }
  194.         }
  195.     }
  196.     
  197.     if (printIt)
  198.         PrintResponse(rp);
  199.     else if (gTrace == kTracingOn)
  200.         TraceResponse(rp);
  201. }    /* PrintResponseIfNeeded */
  202.  
  203.  
  204.  
  205.  
  206. void DoneWithResponse(ResponsePtr rp)
  207. {
  208.     /* Dispose space taken up by the Response, and clear it out
  209.      * again.  For some reason, I like to return memory to zeroed
  210.      * when not in use.
  211.      */
  212.     if (rp != NULL) {
  213.         PrintResponseIfNeeded(rp);
  214.         DisposeLineListContents(&rp->msg);
  215.         CLEARRESPONSE(rp);
  216.         free(rp);
  217.     }
  218. }    /* DoneWithResponse */
  219.  
  220.  
  221.  
  222.  
  223. /* This takes an existing Response and recycles it, by clearing out
  224.  * the current contents.
  225.  */
  226. void ReInitResponse(ResponsePtr rp)
  227. {
  228.     PrintResponseIfNeeded(rp);
  229.     DisposeLineListContents(&rp->msg);
  230.     CLEARRESPONSE(rp);
  231. }    /* ReInitResponse */
  232.  
  233.  
  234.  
  235. static
  236. void TimeoutGetTelnetString(int unused)
  237. {
  238.     alarm(0);
  239.     longjmp(gTStrTimeOut, 1);
  240. }    /* TimeoutGetTelnetString */
  241.  
  242.  
  243.  
  244. /* Since the control stream is defined by the Telnet protocol (RFC 854),
  245.  * we follow Telnet rules when reading the control stream.  We use this
  246.  * routine when we want to read a response from the host.
  247.  */
  248. int GetTelnetString(char *str, size_t siz, FILE *cin, FILE *cout)
  249. {
  250.     int c;
  251.     size_t n;
  252.     int eofError;
  253.     char *cp;
  254.  
  255.     if ((cin == NULL) || (cout == NULL)) {
  256.         eofError = -1;
  257.         goto done;
  258.     }
  259.  
  260.     if (setjmp(gTStrTimeOut) != 0) {
  261.         Error(kDontPerror, "Host is not responding to commands, hanging up.\n");
  262.         if (gAttemptingConnection == 0) {
  263.             HangupOnServer();
  264.             if (!gDoneApplication) {
  265.                 alarm(0);
  266.                 longjmp(gCmdLoopJmp, 1);
  267.             }
  268.         } else {
  269.             /* Give up and return to Open(). */
  270.             DoClose(0);
  271.         }
  272.         eofError = -1;
  273.         goto done;
  274.     }
  275.     SIGNAL(SIGALRM, TimeoutGetTelnetString);
  276.     alarm(gNetworkTimeout);
  277.  
  278.     cp = str;
  279.     --siz;        /* We'll need room for the \0. */
  280.     for (n = (size_t)0, eofError = 0; ; ) {
  281.         c = fgetc(cin);
  282. checkChar:
  283.         if (c == EOF) {
  284. eof:
  285.             eofError = -1;
  286.             break;
  287.         } else if (c == '\r') {
  288.             /* A telnet string can have a CR by itself.  But to denote that,
  289.              * the protocol uses \r\0;  an end of line is denoted \r\n.
  290.              */
  291.             c = fgetc(cin);
  292.             if (c == '\n') {
  293.                 /* Had \r\n, so done. */
  294.                 goto done;
  295.             } else if (c == EOF) {
  296.                 goto eof;
  297.             } else if (c == '\0') {
  298.                 c = '\r';
  299.                 goto addChar;
  300.             } else {
  301.                 /* Telnet protocol violation! */
  302.                 goto checkChar;
  303.             }
  304.         } else if (c == '\n') {
  305.             /* Really shouldn't get here.  If we do, the other side
  306.              * violated the TELNET protocol, since eoln's are CR/LF,
  307.              * and not just LF.
  308.              */
  309.             DebugMsg("TELNET protocol violation:  raw LF.\n");
  310.             goto done;
  311.         } else if (c == IAC) {
  312.             /* Since the control connection uses the TELNET protocol,
  313.              * we have to handle some of its commands ourselves.
  314.              * IAC is the protocol's escape character, meaning that
  315.              * the next character after the IAC (Interpret as Command)
  316.              * character is a telnet command.  But, if there just
  317.              * happened to be a character in the text stream with the
  318.              * same numerical value of IAC, 255, the sender denotes
  319.              * that by having an IAC followed by another IAC.
  320.              */
  321.             
  322.             /* Get the telnet command. */
  323.             c = fgetc(cin);
  324.             
  325.             switch (c) {
  326.                 case WILL:
  327.                 case WONT:
  328.                     /* Get the option code. */
  329.                     c = fgetc(cin);
  330.                     
  331.                     /* Tell the other side that we don't want
  332.                      * to do what they're offering to do.
  333.                      */
  334.                     (void) fprintf(cout, "%c%c%c",IAC,DONT,c);
  335.                     (void) fflush(cout);
  336.                     break;
  337.                 case DO:
  338.                 case DONT:
  339.                     /* Get the option code. */
  340.                     c = fgetc(cin);
  341.                     
  342.                     /* The other side said they are DOing (or not)
  343.                      * something, which would happen if our side
  344.                      * asked them to.  Since we didn't do that,
  345.                      * ask them to not do this option.
  346.                      */
  347.                     (void) fprintf(cout, "%c%c%c",IAC,WONT,c);
  348.                     (void) fflush(cout);
  349.                     break;
  350.  
  351.                 case EOF:
  352.                     goto eof;
  353.  
  354.                 default:
  355.                     /* Just add this character, since it was most likely
  356.                      * just an escaped IAC character.
  357.                      */
  358.                     goto addChar;
  359.             }
  360.         } else {
  361. addChar:
  362.             /* If the buffer supplied has room, add this character to it. */
  363.             if (n < siz) {
  364.                 *cp++ = c;                
  365.                 ++n;
  366.             }
  367.         }
  368.     }
  369.  
  370. done:
  371.     *cp = '\0';
  372.     alarm(0);
  373.     return (eofError);
  374. }    /* GetTelnetString */
  375.  
  376.  
  377.  
  378. /* Returns the code class of the command, or 5 if an error occurs, which
  379.  * coincides with the error class anyway.  This reads the entire response
  380.  * text into a LineList, which is kept in the 'Response' structure.
  381.  */
  382. int GetResponse(ResponsePtr rp)
  383. {
  384.     string str;
  385.     int eofError;
  386.     str16 code;
  387.     char *cp;
  388.     int continuation;
  389.     int usedTmpRp;
  390.     int codeType;
  391.  
  392.     /* You can tell us to do the default action on the response,
  393.      * or tell us to ignore the response if the caller doesn't want
  394.      * to handle it.
  395.      */
  396.     usedTmpRp = 1;
  397.     if (rp == kDefaultResponse) {
  398.         rp = InitResponse();
  399.     } else if (rp == kIgnoreResponse) {
  400.         rp = InitResponse();
  401.         rp->printMode = kDontPrint;
  402.     } else
  403.         usedTmpRp = 0;
  404.  
  405.     /* RFC 959 states that a reply may span multiple lines.  A single
  406.      * line message would have the 3-digit code <space> then the msg.
  407.      * A multi-line message would have the code <dash> and the first
  408.      * line of the msg, then additional lines, until the last line,
  409.      * which has the code <space> and last line of the msg.
  410.      *
  411.      * For example:
  412.      *    123-First line
  413.      *    Second line
  414.      *    234 A line beginning with numbers
  415.      *    123 The last line
  416.      */
  417.  
  418.     /* Get the first line of the response. */
  419.     eofError = GetTelnetString(str, sizeof(str), gControlIn, gControlOut);
  420.     if (eofError < 0)
  421.         goto eof;
  422.  
  423.     cp = str;
  424.     if (!isdigit(*cp)) {
  425.         Error(kDontPerror, "Invalid reply: \"%s\"\n", cp);
  426.         return (5);
  427.     }
  428.  
  429.     codeType = rp->codeType = *cp - '0';
  430.     cp += 3;
  431.     continuation = (*cp == '-');
  432.     *cp++ = '\0';
  433.     STRNCPY(code, str);
  434.     rp->code = atoi(code);
  435.     AddLine(&rp->msg, cp);
  436.     
  437.     while (continuation) {
  438.         eofError = GetTelnetString(str, sizeof(str), gControlIn, gControlOut);
  439.         if (eofError < 0) {
  440.             /* Most of the time, we don't want EOFs from the other side. */
  441. eof:
  442.             if (*str)
  443.                 AddLine(&rp->msg, str);
  444. eofMsg:
  445.             if (rp->eofOkay == 0)
  446.                 Error(kDontPerror, "Remote host has closed the connection.\n");
  447.             rp->hadEof = 1;
  448.             if (gAttemptingConnection == 0) {
  449.                 HangupOnServer();
  450.                 if (!gDoneApplication) {
  451.                     alarm(0);
  452.                     longjmp(gCmdLoopJmp, 1);
  453.                 }
  454.             } else if (rp->eofOkay == 0) {
  455.                 /* Give up and return to Open(). */
  456.                 DoClose(0);
  457.             }    /* else rp->eofOkay, which meant we already closed. */
  458.             return (5);
  459.         }
  460.         cp = str;
  461.         if (strncmp(code, cp, SZ(3)) == 0) {
  462.             cp += 3;
  463.             if (*cp == ' ')
  464.                 continuation = 0;
  465.             ++cp;
  466.         }
  467.         AddLine(&rp->msg, cp);
  468.     }
  469.  
  470.     if (rp->code == 421) {
  471.         /*
  472.          *   421 Service not available, closing control connection.
  473.          *       This may be a reply to any command if the service knows it
  474.          *       must shut down.
  475.          */
  476.         goto eofMsg;
  477.     }
  478.  
  479.     /* From above, if the caller didn't want to handle it, we kept our
  480.      * own copy and now it's time to dispose of it.  Depending on
  481.      * whether we're ignoring it altogether or doing the default
  482.      * action, we may or may not print it before deallocating it.
  483.      */
  484.     if (usedTmpRp)
  485.         DoneWithResponse(rp);
  486.  
  487.     return (codeType);
  488. }    /* GetResponse */
  489.  
  490.  
  491.  
  492.  
  493. /* This creates the complete command text to send, and writes it
  494.  * on the stream.
  495.  */
  496. static
  497. void SendCommand(char *cmdspec, va_list ap)
  498. {
  499.     longstring command;
  500.     int result;
  501.  
  502.     (void) vsprintf(command, cmdspec, ap);
  503.     if (strncmp(command, "PASS", SZ(4)))
  504.         DebugMsg("RCmd:  \"%s\"\n", command);
  505.     else
  506.         DebugMsg("RCmd:  \"%s\"\n", "PASS xxxxxxxx");
  507.     STRNCAT(command, "\r\n");    /* Use TELNET end-of-line. */
  508.     if (gControlOut != NULL) {
  509.         result = fputs(command, gControlOut);
  510.         if (result < 0)
  511.             Error(kDoPerror, "Could not write to control stream.\n");
  512.         (void) fflush(gControlOut);
  513.     }
  514. }    /* SendCommand */
  515.  
  516.  
  517.  
  518.  
  519. /* For "simple" (i.e. not data transfer) commands, this routine is used
  520.  * to send the command and receive one response.  It returns the codeClass
  521.  * field of the 'Response' as the result.
  522.  */
  523.  
  524. /*VARARGS*/
  525. #ifndef HAVE_STDARG_H
  526. int RCmd(va_alist)
  527.         va_dcl
  528. #else
  529. int RCmd(ResponsePtr rp0, char *cmdspec0, ...)
  530. #endif
  531. {
  532.     va_list ap;
  533.     char *cmdspec;
  534.     ResponsePtr rp;
  535.     int result;
  536.  
  537. #ifndef HAVE_STDARG_H
  538.     va_start(ap);
  539.     rp = va_arg(ap, ResponsePtr);
  540.     cmdspec = va_arg(ap, char *);
  541. #else
  542.     va_start(ap, cmdspec0);
  543.     cmdspec = cmdspec0;
  544.     rp = rp0;
  545. #endif
  546.     if (gControlOut == NULL) {
  547.         va_end(ap);
  548.         return (-1);
  549.     }
  550.  
  551.     SendCommand(cmdspec, ap);
  552.     va_end(ap);
  553.  
  554.     /* Get the response to the command we sent. */
  555.     result = GetResponse(rp);
  556.  
  557.     return (result);
  558. }    /* RCmd */
  559.  
  560.  
  561.  
  562. /* Returns -1 if an error occurred, or 0 if not.
  563.  * This differs from RCmd, which returns the code class of a response.
  564.  */
  565.  
  566. /*VARARGS*/
  567. #ifndef HAVE_STDARG_H
  568. int RDataCmd(va_alist)
  569.         va_dcl
  570. #else
  571. int RDataCmd(XferSpecPtr xp0, char *cmdspec0, ...)
  572. #endif
  573. {
  574.     va_list ap;
  575.     char *cmdspec;
  576.     XferSpecPtr xp;
  577.     int result, didXfer;
  578.     int respCode;
  579.     int ioErrs;
  580.  
  581. #ifndef HAVE_STDARG_H
  582.     va_start(ap);
  583.     xp = va_arg(ap, XferSpecPtr);
  584.     cmdspec = va_arg(ap, char *);
  585. #else
  586.     va_start(ap, cmdspec0);
  587.     cmdspec = cmdspec0;
  588.     xp = xp0;
  589. #endif
  590.  
  591.     if (gControlOut == NULL) {
  592.         va_end(ap);
  593.         return (-1);
  594.     }
  595.  
  596.     /* To transfer data, we do these things in order as specifed by
  597.      * the RFC.
  598.      * 
  599.      * First, we tell the other side to set up a data line.  This
  600.      * is done below by calling OpenDataConnection(), which sets up
  601.      * the socket.  When we do that, the other side detects a connection
  602.      * attempt, so it knows we're there.  Then tell the other side
  603.      * (by using listen()) that we're willing to receive a connection
  604.      * going to our side.
  605.      */
  606.     didXfer = 0;
  607.  
  608.     if ((result = OpenDataConnection(gPreferredDataPortMode)) < 0)
  609.         goto done;
  610.  
  611.     /* If asked, attempt to start at a later position in the remote file. */
  612.     if (xp->startPoint != SZ(0)) {
  613.         if (SetStartOffset(xp->startPoint) < 0) {
  614.             xp->startPoint = SZ(0);
  615.             TruncReOpenReceiveFile(xp);
  616.         }
  617.     }
  618.  
  619.     /* Now we tell the server what we want to do.  This sends the
  620.      * the type of transfer we want (RETR, STOR, LIST, etc) and the
  621.      * parameters for that (files to send, directories to list, etc).
  622.      */
  623.     SendCommand(cmdspec, ap);
  624.  
  625.     /* Get the response to the transfer command we sent, to see if
  626.      * they can accomodate the request.  If everything went okay,
  627.      * we will get a preliminary response saying that the transfer
  628.      * initiation was successful and that the data is there for
  629.      * reading (for retrieves;  for sends, they will be waiting for
  630.      * us to send them something).
  631.      */
  632.     respCode = GetResponse(xp->cmdResp);
  633.     DoneWithResponse(xp->cmdResp);
  634.     xp->cmdResp = NULL;
  635.  
  636.     if (respCode > 2) {
  637.         result = -1;
  638.         goto done;
  639.     }
  640.  
  641.     /* Now we accept the data connection that the other side is offering
  642.      * to us.  Then we can do the actual I/O on the data we want.
  643.      */
  644.     if ((result = AcceptDataConnection(xp->netMode)) < 0)
  645.         goto done;
  646.  
  647.     if (NETREADING(xp))
  648.         xp->inStream = gDataSocket;
  649.     else
  650.         xp->outStream = gDataSocket;
  651.  
  652.     ioErrs = DataTransfer(xp);
  653.     didXfer = 1;
  654.     result = ioErrs ? -1 : 0;
  655.  
  656. done:
  657.     CloseDataConnection();
  658.     if (didXfer) {
  659. #if 0
  660.         /* Get the response to the data transferred.  Most likely a message
  661.          * saying that the transfer completed succesfully.  However, if
  662.          * we tried to abort a transfer in progress, but didn't in time,
  663.          * we will already have the reply courtesy of AbortDataTransfer()
  664.          * so should not get a response.
  665.          */
  666.         if (xp->xferResp != NULL) {
  667.             respCode = GetResponse(xp->xferResp);
  668.             if (respCode != 2)
  669.                 result = -1;
  670.         }
  671. #else
  672.         /* Get the response to the data transferred.  Most likely a message
  673.          * saying that the transfer completed succesfully.  However, if
  674.          * we tried to abort the transfer using ABOR, we will have a response
  675.          * to that command instead.
  676.          */
  677.         respCode = GetResponse(xp->xferResp);
  678.         if (respCode != 2)
  679.             result = -1;
  680. #endif
  681.     }
  682.     va_end(ap);
  683.     return (result);
  684. }    /* RDataCmd */
  685.  
  686.  
  687.  
  688. /*****************************************************************************
  689.  
  690. How command responses are handled.
  691. ----------------------------------
  692.  
  693. Older versions of the program were built upon the BSD ftp client.  It's method
  694. was just to send commands, and at arbitrary points, read and print the
  695. response.
  696.  
  697. I want to keep responses together, and have them read automatically, but have
  698. the option of not printing them, printing them some other time, or just
  699. getting a response and parsing the results.  The BSD client needed to do that
  700. a lot, but it used a verbosity variable, and when it wanted to do that, would
  701. set the verbosity to some "quiet" value.  That turned out to be quite a mess
  702. of setting, saving, and restoring the verbosity level, not to mention being
  703. unflexible.  There is a verbosity variable, but it has a much-reduced role
  704. than it did before.
  705.  
  706. I have a structure, the 'Response' structure, defined in the RCmd.h header.
  707. Besides keeping the entire response text, it keeps with it the code class,
  708. the actual response code, and some other stuff.
  709.  
  710. All commands are sent to a central function, which require a pointer to an
  711. initialized Response as an argument.  After the command is sent, the Response
  712. is filled in. The response text may be printed automatically if an error
  713. occurred, and if the user had that setting on.  Otherwise, it is the caller's
  714. responsibility to print it if it likes, and also to dispose of the structure
  715. when finished.  Much of the time, we don't even need to print anything, to
  716. keep the gory details from the user anyway.
  717.  
  718. Typically, if a calling function needs to examine the response after the
  719. command completes, the caller will have something like this:
  720.     ResponsePtr resp;
  721.     resp = InitResponse();
  722.     RCmd(...);
  723.     [do something with the response]
  724.     DoneWithResponse(resp);
  725.  
  726. Other times we may want to just do a command but don't care about the
  727. result unless it was an error.  In that case we don't have to setup a
  728. Response block.  We can pass a special parameter to RCmd, and maybe
  729. take action depending if the command failed:
  730.     if (RCmd(kDefaultResponse, ...) != 2) { error... }
  731.  
  732. Another thing we may want is to just do a command, and not even care
  733. if it succeeded or not:
  734.     (void) RCmd(kIgnoreResponse, ...);
  735.     
  736. *****************************************************************************/
  737.  
  738. /* eof */
  739.