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