innfeed/connection.h

   1 /*  $Id: connection.h 6648 2004-01-25 20:07:11Z rra $
   2 **
   3 **  The public interface to the Connection class.
   4 **
   5 **  Written by James Brister <brister@vix.com>
   6 **
   7 **  The Connection class encapulates an NNTP protocol endpoint (either regular
   8 **  or extended with the streaming protocol).  Each Connection is owned by a
   9 **  single Host object.
  10 **
  11 **  It manages the network connection (via an EndPoint) the the pumping of
  12 **  articles to the remote host.  It gets these articles from its Host object.
  13 **  If the remote doesn't handle the streaming extension, then the Connection
  14 **  will only manage one article at a time.  If the remote handles the
  15 **  extension, then the connection will queue up articles while sending the
  16 **  CHECK and TAKETHIS commands.
  17 **
  18 **  If the network connection drops while the Connection object has articles
  19 **  queued up, then it will hand them back to its Host object.
  20 */
  21
  22 #if ! defined ( connection_h__ )
  23 #define connection_h__
  24
  25
  26 #include <time.h>
  27 #include <stdio.h>
  28
  29 #include "misc.h"
  30
  31
  32   /*
  33    * Create a new Connection.
  34    *
  35    * HOST is the host object we're owned by.
  36    * IDENT is an identifier to be added to syslog entries so we can tell
  37    *    what's happening on different connections to the same peer.
  38    * IPNAME is the name (or ip address) of the remote)
  39    * MAXTOUT is the maximum amount of time to wait for a response before
  40    *    considering the remote host dead.
  41    * PORTNUM is the portnum to contact on the remote end.
  42    * RESPTIMEOUT is the amount of time to wait for a response from a remote
  43    *    before considering the connection dead.
  44    * CLOSEPERIOD is the number of seconds after connecting that the
  45    *     connections should be closed down and reinitialized (due to problems
  46    *     with old NNTP servers that hold history files open. Value of 0 means
  47    *     no close down.
  48    */
  49 Connection newConnection (Host host,
  50                           unsigned int ident,
  51                           const char *ipname,
  52                           unsigned int artTout,
  53                           unsigned int portNum,
  54                           unsigned int respTimeout,
  55                           unsigned int closePeriod,
  56                           double lowPassLow,
  57                           double lowPassHigh,
  58                           double lowPassFilter) ;
  59
  60   /* Causes the Connection to build the network connection. */
  61 bool cxnConnect (Connection cxn) ;
  62
  63   /* puts the connection into the wait state (i.e. waits for an article
  64      before initiating a connect). Can only be called right after
  65      newConnection returns, or while the Connection is in the (internal)
  66      Sleeping state. */
  67 void cxnWait (Connection cxn) ;
  68
  69   /* The Connection will disconnect as if cxnDisconnect were called and then
  70      it automatically reconnects to the remote. */
  71 void cxnFlush (Connection cxn) ;
  72
  73   /* The Connection sends remaining articles, then issues a QUIT and then
  74      deletes itself */
  75 void cxnClose (Connection cxn) ;
  76
  77   /* The Connection drops all queueed articles, then issues a QUIT and then
  78      deletes itself */
  79 void cxnTerminate (Connection cxn) ;
  80
  81   /* Blow away the connection gracelessly and immedately clean up */
  82 void cxnNuke (Connection cxn) ;
  83
  84   /* Tells the Connection to take the article and handle its
  85      transmission. If it can't (due to queue size or whatever), then the
  86      function returns false. The connection assumes ownership of the
  87      article if it accepts it (returns true). */
  88 bool cxnTakeArticle (Connection cxn, Article art) ;
  89
  90   /* Tell the Connection to take the article (if it can) for later
  91      processing. Assumes ownership of it if it takes it. */
  92 bool cxnQueueArticle (Connection cxn, Article art) ;
  93
  94   /* generate a syslog message for the connections activity. Called by Host. */
  95 void cxnLogStats (Connection cxn, bool final) ;
  96
  97   /* return the number of articles the connection can be given. This lets
  98      the host shovel in as many as possible. May be zero. */
  99 size_t cxnQueueSpace (Connection cxn) ;
 100
 101   /* adjust the mode no-CHECK filter values */
 102 void cxnSetCheckThresholds (Connection cxn,
 103                             double lowFilter, double highFilter,
 104                             double lowPassFilter) ;
 105
 106   /* print some debugging info. */
 107 void gPrintCxnInfo (FILE *fp, unsigned int indentAmt) ;
 108 void printCxnInfo (Connection cxn, FILE *fp, unsigned int indentAmt) ;
 109
 110 /* config file load callback */
 111 int cxnConfigLoadCbk (void *data) ;
 112
 113 /* check connection state is in cxnWaitingS, cxnConnectingS or cxnIdleS */
 114 bool cxnCheckstate (Connection cxn) ;
 115
 116 #endif /* connection_h__ */