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