1/* conn.h
2   Header file for routines which manipulate connections.
3
4   Copyright (C) 1991, 1992, 1993, 1994, 2002 Ian Lance Taylor
5
6   This file is part of the Taylor UUCP package.
7
8   This program is free software; you can redistribute it and/or
9   modify it under the terms of the GNU General Public License as
10   published by the Free Software Foundation; either version 2 of the
11   License, or (at your option) any later version.
12
13   This program is distributed in the hope that it will be useful, but
14   WITHOUT ANY WARRANTY; without even the implied warranty of
15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
16   General Public License for more details.
17
18   You should have received a copy of the GNU General Public License
19   along with this program; if not, write to the Free Software
20   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307, USA.
21
22   The author of the program may be contacted at ian@airs.com.
23   */
24
25#ifndef CONN_H
26
27#define CONN_H
28
29#if ANSI_C
30/* These structures are used in prototypes but are not defined in this
31   header file.  */
32struct uuconf_system;
33struct uuconf_dialer;
34struct uuconf_chat;
35#endif
36
37/* This structure represents a connection.  */
38
39struct sconnection
40{
41  /* Pointer to command table for this type of connection.  */
42  const struct sconncmds *qcmds;
43  /* Pointer to system dependent information.  */
44  pointer psysdep;
45  /* Pointer to system independent information.  */
46  struct uuconf_port *qport;
47};
48
49/* Whether fconn_dial got a dialer.  */
50
51enum tdialerfound
52{
53  /* Did not find a dialer.  */
54  DIALERFOUND_FALSE,
55  /* Found a dialer which does not need to be freed.  */
56  DIALERFOUND_TRUE,
57  /* Found a dialer which does need to be freed.  */
58  DIALERFOUND_FREE
59};
60
61/* Parity settings to pass to fconn_set.  */
62
63enum tparitysetting
64{
65  /* Do not change output parity generation.  */
66  PARITYSETTING_DEFAULT,
67  /* No parity (all eight output bits used).  */
68  PARITYSETTING_NONE,
69  /* Even parity.  */
70  PARITYSETTING_EVEN,
71  /* Odd parity.  */
72  PARITYSETTING_ODD,
73  /* Mark parity.  */
74  PARITYSETTING_MARK,
75  /* Space parity.  */
76  PARITYSETTING_SPACE
77};
78
79/* Type of strip control argument to fconn_set.  */
80
81enum tstripsetting
82{
83  /* Do not change the stripping of input characters.  */
84  STRIPSETTING_DEFAULT,
85  /* Do not strip input characters to seven bits.  */
86  STRIPSETTING_EIGHTBITS,
87  /* Strip input characters to seven bits.  */
88  STRIPSETTING_SEVENBITS
89};
90
91/* Type of XON/XOFF control argument to fconn_set.  */
92
93enum txonxoffsetting
94{
95  /* Do not change XON/XOFF handshake setting.  */
96  XONXOFF_DEFAULT,
97  /* Do not do XON/XOFF handshaking.  */
98  XONXOFF_OFF,
99  /* Do XON/XOFF handshaking.  */
100  XONXOFF_ON
101};
102
103/* A command table holds the functions which implement actions for
104   each different kind of connection.  */
105
106struct sconncmds
107{
108  /* Free up a connection.  */
109  void (*pufree) P((struct sconnection *qconn));
110  /* Lock the connection.  The fin argument is TRUE if the connection
111     is to be used for an incoming call.  The fuser argument is TRUE
112     if, should the port be opened, it should be opened using the
113     user's permissions rather than the effective permissions.  May be
114     NULL.  */
115  boolean (*pflock) P((struct sconnection *qconn, boolean fin, boolean fuser));
116  /* Unlock the connection.  May be NULL.  */
117  boolean (*pfunlock) P((struct sconnection *qconn));
118  /* Open the connection.  */
119  boolean (*pfopen) P((struct sconnection *qconn, long ibaud,
120		       boolean fwait, boolean fuser));
121  /* Close the connection.  */
122  boolean (*pfclose) P((struct sconnection *qconn,
123			pointer puuconf,
124			struct uuconf_dialer *qdialer,
125			boolean fsuccess));
126  /* Dial a number on a connection.  This set *qdialer to the dialer
127     used, if any, and sets *ptdialerfound appropriately.  The qsys
128     and zphone arguments are for the chat script.  This field may be
129     NULL.  */
130  boolean (*pfdial) P((struct sconnection *qconn, pointer puuconf,
131		       const struct uuconf_system *qsys,
132		       const char *zphone,
133		       struct uuconf_dialer *qdialer,
134		       enum tdialerfound *ptdialerfound));
135  /* Read data from a connection, with a timeout in seconds.  When
136     called *pclen is the length of the buffer; on successful return
137     *pclen is the number of bytes read into the buffer.  The cmin
138     argument is the minimum number of bytes to read before returning
139     ahead of a timeout.  */
140  boolean (*pfread) P((struct sconnection *qconn, char *zbuf, size_t *pclen,
141		       size_t cmin, int ctimeout, boolean freport));
142  /* Write data to the connection.  */
143  boolean (*pfwrite) P((struct sconnection *qconn, const char *zbuf,
144			size_t clen));
145  /* Read and write data to the connection.  This reads and writes
146     data until either all passed in data has been written or the read
147     buffer has been filled.  When called *pcread is the size of the
148     read buffer and *pcwrite is the number of bytes to write; on
149     successful return *pcread is the number of bytes read and
150     *pcwrite is the number of bytes written.  */
151  boolean (*pfio) P((struct sconnection *qconn, const char *zwrite,
152		     size_t *pcwrite, char *zread, size_t *pcread));
153  /* Send a break character.  This field may be NULL.  */
154  boolean (*pfbreak) P((struct sconnection *qconn));
155  /* Change the connection setting.  This field may be NULL.  */
156  boolean (*pfset) P((struct sconnection *qconn,
157		      enum tparitysetting tparity,
158		      enum tstripsetting tstrip,
159		      enum txonxoffsetting txonxoff));
160  /* Require or ignore carrer.  This field may be NULL.  */
161  boolean (*pfcarrier) P((struct sconnection *qconn,
162			  boolean fcarrier));
163  /* Run a chat program on a connection.  */
164  boolean (*pfchat) P((struct sconnection *qconn, char **pzprog));
165  /* Get the baud rate of a connection.  This field may be NULL.  */
166  long (*pibaud) P((struct sconnection *qconn));
167};
168
169/* Connection functions.  */
170
171/* Initialize a connection.  This must be called before any of the
172   other connection functions are called.  It initializes the fields
173   of qconn.  If qport is NULL, this opens standard input as a port
174   using type ttype.  This function returns FALSE on error.  */
175extern boolean fconn_init P((struct uuconf_port *qport,
176			     struct sconnection *qconn,
177			     enum uuconf_porttype ttype));
178
179/* Free up connection data.  */
180extern void uconn_free P((struct sconnection *qconn));
181
182/* Lock a connection.  The fin argument is TRUE if the port is to be
183   used for an incoming call; certains type of Unix locking need this
184   information because they need to open the port.  The fuser argument
185   is TRUE if, should the port be opened, it should be opened using
186   the user's permissions rather than the effective permissions.  */
187extern boolean fconn_lock P((struct sconnection *qconn, boolean fin,
188			     boolean fuser));
189
190/* Unlock a connection.  */
191extern boolean fconn_unlock P((struct sconnection *qconn));
192
193/* Open a connection.  If ibaud is 0, the natural baud rate of the
194   port is used.  If ihighbaud is not 0, fconn_open chooses the
195   highest supported baud rate between ibaud and ihighbaud.  If fwait
196   is TRUE, this should wait for an incoming call.  If fuser is true,
197   the device should be opened using the user's permissions rather
198   than the effective permissions.  */
199extern boolean fconn_open P((struct sconnection *qconn, long ibaud,
200			     long ihighbaud, boolean fwait,
201			     boolean fuser));
202
203/* Close a connection.  The fsuccess argument is TRUE if the
204   conversation completed normally, FALSE if it is being aborted.  */
205extern boolean fconn_close P((struct sconnection *qconn,
206			      pointer puuconf,
207			      struct uuconf_dialer *qdialer,
208			      boolean fsuccess));
209
210/* Dial out on a connection.  The qsys and zphone arguments are for
211   the chat scripts; zphone is the phone number to dial.  If qdialer
212   is not NULL, *qdialer will be set to the dialer information used if
213   any; *ptdialerfound will be set appropriately.  */
214extern boolean fconn_dial P((struct sconnection *q, pointer puuconf,
215			     const struct uuconf_system *qsys,
216			     const char *zphone,
217			     struct uuconf_dialer *qdialer,
218			     enum tdialerfound *ptdialerfound));
219
220/* Read from a connection.
221   zbuf -- buffer to read bytes into
222   *pclen on call -- length of zbuf
223   *pclen on successful return -- number of bytes read
224   cmin -- minimum number of bytes to read before returning ahead of timeout
225   ctimeout -- timeout in seconds, 0 if none
226   freport -- whether to report errors.  */
227extern boolean fconn_read P((struct sconnection *qconn, char *zbuf,
228			     size_t *pclen, size_t cmin,
229			     int ctimeout, boolean freport));
230
231/* Write to a connection.  */
232extern boolean fconn_write P((struct sconnection *qconn, const char *zbuf,
233			      size_t cbytes));
234
235/* Read and write to a connection.  This reads and writes data until
236   either all passed-in data has been written or the read buffer is
237   full.
238   zwrite -- buffer to write bytes from
239   *pcwrite on call -- number of bytes to write
240   *pcwrite on successful return -- number of bytes written
241   zread -- buffer to read bytes into
242   *pcread on call -- size of read buffer
243   *pcread on successful return -- number of bytes read.  */
244extern boolean fconn_io P((struct sconnection *qconn, const char *zwrite,
245			   size_t *pcwrite, char *zread, size_t *pcread));
246
247/* Send a break character to a connection.  */
248extern boolean fconn_break P((struct sconnection *qconn));
249
250/* Change the settings of a connection.  This allows independent
251   control over the parity of output characters, whether to strip
252   input characters, and whether to do XON/XOFF handshaking.  There is
253   no explicit control over parity checking of input characters.  This
254   function returns FALSE on error.  Attempts to set values not
255   supported by the hardware are silently ignored.  */
256extern boolean fconn_set P((struct sconnection *qconn,
257			    enum tparitysetting tparity,
258			    enum tstripsetting tstrip,
259			    enum txonxoffsetting txonxoff));
260
261/* Get the baud rate of a connection.  */
262extern long iconn_baud P((struct sconnection *qconn));
263
264/* Do a chat script with a system.  */
265extern boolean fchat P((struct sconnection *qconn, pointer puuconf,
266			const struct uuconf_chat *qchat,
267			const struct uuconf_system *qsys,
268			const struct uuconf_dialer *qdialer,
269			const char *zphone, boolean ftranslate,
270			const char *zport, long ibaud));
271
272/* Tell the connection to either require or ignore carrier as fcarrier
273   is TRUE or FALSE respectively.  This is called with fcarrier TRUE
274   when \m is encountered in a chat script, and with fcarrier FALSE
275   when \M is encountered.  */
276extern boolean fconn_carrier P((struct sconnection *qconn,
277				boolean fcarrier));
278
279/* Run a chat program on a connection.  */
280extern boolean fconn_run_chat P((struct sconnection *qconn,
281				 char **pzprog));
282
283/* Run through a dialer sequence.  This is a support routine for the
284   port type specific dialing routines.  */
285extern boolean fconn_dial_sequence P((struct sconnection *qconn,
286				      pointer puuconf, char **pzdialer,
287				      const struct uuconf_system *qsys,
288				      const char *zphone,
289				      struct uuconf_dialer *qdialer,
290				      enum tdialerfound *ptdialerfound));
291
292/* Dialing out on a modem is partially system independent.  This is
293   the modem dialing routine.  */
294extern boolean fmodem_dial P((struct sconnection *qconn, pointer puuconf,
295			      const struct uuconf_system *qsys,
296			      const char *zphone,
297			      struct uuconf_dialer *qdialer,
298			      enum tdialerfound *ptdialerfound));
299
300/* Begin dialing out.  This should open the dialer device if there is
301   one, toggle DTR if requested and possible, and tell the port to
302   ignore carrier.  It should return FALSE on error.  */
303extern boolean fsysdep_modem_begin_dial P((struct sconnection *qconn,
304					   struct uuconf_dialer *qdial));
305
306/* Finish dialing out on a modem.  This should close the dialer device
307   if there is one.  If the dialer and the port both support carrier,
308   the connection should be told to pay attention to carrier.  If it
309   is possible to wait for carrier to come on, and the dialer and the
310   port both the port support carrier, it should wait until carrier
311   comes on.  */
312extern boolean fsysdep_modem_end_dial P((struct sconnection *qconn,
313					 struct uuconf_dialer *qdial));
314
315/* System dependent initialization routines.  */
316extern boolean fsysdep_stdin_init P((struct sconnection *qconn));
317extern boolean fsysdep_modem_init P((struct sconnection *qconn));
318extern boolean fsysdep_direct_init P((struct sconnection *qconn));
319#if HAVE_TCP
320extern boolean fsysdep_tcp_init P((struct sconnection *qconn));
321#endif
322#if HAVE_TLI
323extern boolean fsysdep_tli_init P((struct sconnection *qconn));
324#endif
325extern boolean fsysdep_pipe_init P((struct sconnection *qconn));
326
327#endif /* ! defined (CONN_H) */
328