3 * $Id: txport.h,v 1.2 2002/01/30 09:27:10 mdw Exp $
5 * Transport switch glue
7 * (c) 2001 Mark Wooding
10 /*----- Licensing notice --------------------------------------------------*
12 * This file is part of Jog: Programming for a jogging machine.
14 * Jog is free software; you can redistribute it and/or modify
15 * it under the terms of the GNU General Public License as published by
16 * the Free Software Foundation; either version 2 of the License, or
17 * (at your option) any later version.
19 * Jog is distributed in the hope that it will be useful,
20 * but WITHOUT ANY WARRANTY; without even the implied warranty of
21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22 * GNU General Public License for more details.
24 * You should have received a copy of the GNU General Public License
25 * along with Jog; if not, write to the Free Software Foundation,
26 * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
29 /*----- Revision history --------------------------------------------------*
32 * Revision 1.2 2002/01/30 09:27:10 mdw
33 * Transport configuration overhaul. Configuration string is now a list of
34 * `;'-separated `key=value' strings, which can be handled either by the
35 * core or the transport module. The newline character(s) are a core
38 * Revision 1.1 2002/01/25 19:34:45 mdw
50 /*----- Header files ------------------------------------------------------*/
61 #include <mLib/darray.h>
62 #include <mLib/lbuf.h>
64 /*----- Data structures ---------------------------------------------------*/
66 /* --- Vector of bytes --- */
70 DA_DECL(uchar_v
, unsigned char);
73 /* --- Node for lines --- */
75 typedef struct txline
{
76 struct txline
*next
, *prev
; /* Next node in the list */
77 struct txport
*tx
; /* Owning transport */
78 char *s
; /* Pointer to the text */
79 size_t len
; /* Length of the string */
82 /* --- A transport context --- *
84 * The only members for which there is contention are the state @s@ and the
85 * raw incoming buffer @buf@. Other members may be accessed without locking
86 * the structure. Thus, the thread messing about is essentially isolated to
87 * the data- fetching thread and the line buffering code.
90 typedef struct txport
{
91 struct txport_ops
*ops
; /* Operations table */
92 pthread_t tid
; /* Fetching thread id */
93 pthread_mutex_t mx
; /* Lock for this structure */
94 pthread_cond_t cv
; /* `New data has arrived' */
95 unsigned s
; /* State of this transport */
96 uchar_v buf
; /* Buffer of incoming data */
97 lbuf lb
; /* Buffer for extracting lines */
98 txline
*ll
, *ll_tail
; /* List of waiting lines, in order */
102 TX_READY
, /* More data may arrive */
103 TX_CLOSE
, /* No more data will arrive */
104 TX_CLOSED
/* Done the closure thing already */
107 /* --- Transport operations --- */
109 struct txfile
{ const char *env
; const char *name
; };
111 typedef struct txport_ops
{
112 struct txport_ops
*next
;
114 const struct txfile
*fv
;
116 txport
*(*create
)(const char */
*file*/
);
117 int (*configure
)(txport */
*tx*/
, const char */
*k*/
, const char */
*v*/
);
118 void *(*fetch
)(void */
*txv*/
);
119 ssize_t (*write
)(txport */
*tx*/
, const void */
*p*/
, size_t /*sz*/);
120 void (*destroy
)(txport */
*tx*/
);
123 /*----- Global variables --------------------------------------------------*/
125 extern txport_ops
*txlist
;
126 extern const char *txname
;
127 extern const char *txfile
;
128 extern const char *txconf
;
130 #define DIRVAR "JOGDIR"
132 /*----- Functions provided ------------------------------------------------*/
134 /* --- @tx_create@ --- *
136 * Arguments: @const char *name@ = name of transport to instantiate
137 * @const char *file@ = filename for transport
138 * @const char *config@ = config string
140 * Returns: A pointer to the transport context, or null on error.
142 * Use: Creates a new transport.
145 extern txport
*tx_create(const char */
*name*/
, const char */
*file*/
,
146 const char */
*config*/
);
148 /* --- @tx_configure@ --- *
150 * Arguments: @txport *tx@ = pointer to transport block
151 * @const char *config@ = config string
153 * Returns: Zero if OK, nonzero on errors.
155 * Use: Applies a configuration string to a transport.
158 extern int tx_configure(txport */
*tx*/
, const char */
*config*/
);
160 /* --- @tx_write@ --- *
162 * Arguments: @txport *tx@ = pointer to transport context
163 * @const void *p@ = pointer to buffer to write
164 * @size_t sz@ = size of buffer
166 * Returns: Zero if OK, or @-1@ on error.
168 * Use: Writes some data to a transport.
171 extern int tx_write(txport */
*tx*/
, const void */
*p*/
, size_t /*sz*/);
173 /* --- @tx_printf@ --- *
175 * Arguments: @txport *tx@ = pointer to transport context
176 * @const char *p@ = pointer to string to write
178 * Returns: The number of characters printed, or @EOF@ on error.
180 * Use: Writes a textual message to a transport.
183 extern int tx_vprintf(txport */
*tx*/
, const char */
*p*/
, va_list */
*ap*/
);
185 extern int tx_printf(txport */
*tx*/
, const char */
*p*/
, ...);
187 /* --- @tx_newline@ --- *
189 * Arguments: @txport *tx@ = pointer to transport context
191 * Returns: Zero if OK, nonzero on error.
193 * Use: Writes a newline (record boundary) to the output.
196 int tx_newline(txport */
*tx*/
);
198 /* --- @tx_read@, @tx_readx@ --- *
200 * Arguments: @txport *tx@ = pointer to transport context
201 * @unsigned long t@ = time to wait for data (ms)
202 * @int (*filter)(const char *s, void *p)@ = filtering function
203 * @void *p@ = pointer argument for filter
205 * Returns: A pointer to a line block, which must be freed using
208 * Use: Fetches a line from the buffer. Each line is passed to the
209 * filter function in oldest-to-newest order; the filter
210 * function returns nonzero to choose a line. If no suitable
211 * line is waiting in the raw buffer, the program blocks while
212 * more data is fetched, until the time limit @t@ is exceeded,
213 * in which case a null pointer is returned. A null filter
214 * function is equivalent to one which always selects its line.
217 #define FOREVER (~0ul)
219 extern txline
*tx_readx(txport */
*tx*/
, unsigned long /*t*/,
220 int (*/
*filter*/
)(const char */
*s*/
, void */
*p*/
),
223 extern txline
*tx_read(txport */
*tx*/
, unsigned long /*t*/);
225 /* --- @tx_freeline@ --- *
227 * Arguments: @txline *l@ = pointer to line
231 * Use: Frees a line block.
234 extern void tx_freeline(txline */
*l*/
);
236 /* --- @tx_destroy@ --- *
238 * Arguments: @txport *tx@ = transport context
242 * Use: Destroys a transport.
245 extern void tx_destroy(txport */
*tx*/
);
247 /*----- That's all, folks -------------------------------------------------*/