1 /**
2  * @defgroup Vio Vio class
3  * @brief    This class provides an I/O layer for files/bufferes/pipes/sockets.
4  *
5  * This class provides an abstraction of I/O to give acess to
6  * files, buffers, pipes, UNIX sockets, and INET sockets.
7  */
8 
9 /**
10  * @file       vio.h
11  * @ingroup    Vio
12  * @brief      Class Vio: virtual <SDIO/FILE/BUFF/UNIX/INET> I/O layer.
13  * @version    $Id: vio.h,v 1.28 2010/08/12 05:40:35 fetk Exp $
14  * @author     Michael Holst
15  *
16  * @attention
17  * @verbatim
18  *
19  * MALOC = < Minimal Abstraction Layer for Object-oriented C >
20  * Copyright (C) 1994-- Michael Holst
21  *
22  * This library is free software; you can redistribute it and/or
23  * modify it under the terms of the GNU Lesser General Public
24  * License as published by the Free Software Foundation; either
25  * version 2.1 of the License, or (at your option) any later version.
26  *
27  * This library is distributed in the hope that it will be useful,
28  * but WITHOUT ANY WARRANTY; without even the implied warranty of
29  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
30  * Lesser General Public License for more details.
31  *
32  * You should have received a copy of the GNU Lesser General Public
33  * License along with this library; if not, write to the Free Software
34  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
35  *
36  * @endverbatim
37  */
38 
39 #ifndef _VIO_H_
40 #define _VIO_H_
41 
42 #include <maloc/maloc_base.h>
43 
44 #include <maloc/vnm.h>
45 
46 /*
47  * ***************************************************************************
48  * Class Vio: Parameters and datatypes
49  * ***************************************************************************
50  */
51 
52 /** @brief our portbase;  5000 < VPORTNUMBER < 49152 */
53 #define VPORTNUMBER 14916
54 /** @brief number of internal buffers (BUFF datatype) */
55 #define VIO_MAXBUF 10
56 
57 /**
58  * @ingroup Vio
59  * @author  Michael Holst
60  * @brief   Parameter for I/O type (sdio,buff,file,unix,inet)
61  */
62 typedef enum VIOtype {
63     VIO_NO_TYPE,
64     VIO_SDIO,
65     VIO_BUFF,
66     VIO_FILE,
67     VIO_UNIX,
68     VIO_INET
69 } VIOtype;
70 
71 /**
72  * @ingroup Vio
73  * @author  Michael Holst
74  * @brief   Parameter for compression type (XDR,ASC)
75  */
76 typedef enum VIOfrmt {
77     VIO_NO_FRMT,
78     VIO_XDR,
79     VIO_ASC
80 } VIOfrmt;
81 
82 /**
83  * @ingroup Vio
84  * @author  Michael Holst
85  * @brief   Parameter for rw type (R,RW)
86  */
87 typedef enum VIOrwkey {
88     VIO_NO_RW,
89     VIO_R,
90     VIO_W
91 } VIOrwkey;
92 
93 /**
94  * @ingroup Vio
95  * @author  Michael Holst
96  * @brief   Contains public data members for Vio class
97  */
98 struct sVio {
99 
100     VIOtype type;       /**< file (or device) type.
101                          *   VIO_NO_TYPE = not initialized.
102                          *   VIO_SDIO    = standard I/O.
103                          *   VIO_FILE    = file I/O.
104                          *   VIO_BUFF    = buffer I/O.
105                          *   VIO_UNIX    = UNIX (domain) socket I/O.
106                          *   VIO_INET    = INET (network) socket I/O.        */
107 
108     VIOfrmt frmt;       /**< data format.
109                          *   VIO_NO_FRMT = not initialized.
110                          *   VIO_ASC     = ASCII (FILE,BUFF,UNIX,INET).
111                          *   VIO_XDR     = BINARY (FILE,BUFF,UNIX,INET).     */
112 
113     VIOrwkey rwkey;     /**< r/w key.
114                          *   VIO_NO_R = not initialized.
115                          *   VIO_R    = read (FILE,BUFF,UNIX,INET)
116                          *   VIO_W    = write (FILE,BUFF,UNIX,INET)          */
117 
118     char file[VMAX_ARGLEN];   /**< file or device name (FILE,BUFF,UNIX,INET) */
119     char lhost[VMAX_ARGLEN];  /**< local hostname (me) (UNIX,INET)           */
120     char rhost[VMAX_ARGLEN];  /**< remote hostname (other guy) (UNIX,INET)   */
121 
122     int error;        /**< note if any error has occurred on this vio device */
123     int dirty;        /**< dirty read bit -- have we read file yet (FILE)    */
124 
125     FILE *fp;         /**< file pointer (SDIO,FILE)                          */
126     int so;           /**< primary unix domain or inet socket (UNIX,INET)    */
127     int soc;          /**< subsocket created for socket reading (UNIX,INET)  */
128     void *name;       /**< &sockaddr_un or &sockaddr_in (UNIX,INET)          */
129     void *axdr;       /**< ASC/XDR structure pointer (ASC,XDR)               */
130 
131     char whiteChars[VMAX_ARGNUM]; /**< white space character set (ASC)       */
132     char commChars[VMAX_ARGNUM];  /**< comment character set (ASC,XDR)       */
133 
134     char ioBuffer[VMAX_BUFSIZE];  /**< I/O buffer (ASC,XDR)                  */
135     int ioBufferLen;              /**< I/O buffer length (ASC,XDR)           */
136 
137     char putBuffer[VMAX_BUFSIZE]; /**< final write buffer (ASC,XDR)          */
138     int putBufferLen;             /**< final write buffer length (ASC,XDR)   */
139 
140     char *VIObuffer;    /**< (BUFF) */
141     int VIObufferLen;   /**< (BUFF) */
142     int VIObufferPtr;   /**< (BUFF) */
143 
144 };
145 
146 /**
147  * @brief   Declaration of the Vio class as the Vio structure
148  * @ingroup Vio
149  * @author  Michael Holst
150  */
151 typedef struct sVio Vio;
152 
153 /*
154  * ***************************************************************************
155  * Class Vio: Inlineable methods (vio.c)
156  * ***************************************************************************
157  */
158 
159 #if !defined(VINLINE_MALOC)
160 #else /* if defined(VINLINE_MALOC) */
161 #endif /* if !defined(VINLINE_MALOC) */
162 
163 /*
164  * ***************************************************************************
165  * Class Vio: Non-Inlineable methods (vio.c)
166  * ***************************************************************************
167  */
168 
169 /**
170  * @ingroup Vio
171  * @brief   Start Vio communication layer (init internal variables/buffers)
172  * @author  Michael Holst
173  * @note    Class Vio: Non-Inlineable methods (vio.c)
174  * @return  None
175  */
176 VEXTERNC void Vio_start(void);
177 
178 /**
179  * @ingroup Vio
180  * @brief   Shutdown Vio communication layer
181  * @author  Michael Holst
182  * @note    Class Vio: Non-Inlineable methods (vio.c)
183  * @return  None
184  */
185 VEXTERNC void Vio_stop(void);
186 
187 /**
188  * @ingroup Vio
189  * @brief   Construct the Vio object
190  * @author  Michael Holst
191  * @note    Class Vio: Non-Inlineable methods (vio.c)
192  * @return  Pointer to newly constructed Vio object
193  * @param   socktype Pointer to the socket type
194  * @param   datafrmt Pointer to the data format
195  * @param   hostname Pointer to network address of port
196  * @param   filename Pointer to the i/o file name
197  * @param   rwkey    Pointer to the read/write options
198  */
199 VEXTERNC Vio* Vio_ctor(const char *socktype, const char *datafrmt,
200     const char *hostname, const char *filename, const char *rwkey);
201 
202 /**
203  * @ingroup Vio
204  * @brief   Work routine that Vio_ctor calls to do most of the construction
205  * @author  Michael Holst
206  * @note    Class Vio: Non-Inlineable methods (vio.c)
207  * @return  1 on success, 0 on failure
208  * @param   thee     Pointer to the Vio object
209  * @param   socktype Pointer to the socket type
210  * @param   datafrmt Pointer to the data format
211  * @param   hostname Pointer to network address of port
212  * @param   filename Pointer to the i/o file name
213  * @param   rwkey    Pointer to the read/write options
214  */
215 VEXTERNC int Vio_ctor2(Vio *thee, const char *socktype, const char *datafrmt,
216     const char *hostname, const char *filename, const char *rwkey);
217 
218 /**
219  * @ingroup Vio
220  * @brief   Destruct the Vio object
221  * @author  Michael Holst
222  * @note    Class Vio: Non-Inlineable methods (vio.c)
223  * @return  None
224  * @param   thee Pointer to the Vio object
225  */
226 VEXTERNC void Vio_dtor(Vio **thee);
227 
228 /**
229  * @ingroup Vio
230  * @brief   Work routine that Vio_dtor calls to do most of the destruction
231  * @author  Michael Holst
232  * @note    Class Vio: Non-Inlineable methods (vio.c)
233  * @return  None
234  * @param   thee Pointer to the Vio object
235  */
236 VEXTERNC void Vio_dtor2(Vio *thee);
237 
238 /**
239  * @ingroup Vio
240  * @brief   Set the white character set for I/O stream
241  * @author  Michael Holst
242  * @note    Class Vio: Non-Inlineable methods (vio.c)
243  * @return  None
244  * @param   thee       Pointer to the Vio object
245  * @param   whiteChars white space character set
246  */
247 VEXTERNC void Vio_setWhiteChars(Vio *thee, char *whiteChars);
248 
249 /**
250  * @ingroup Vio
251  * @brief   Set the comment character set for I/O stream
252  * @author  Michael Holst
253  * @note    Class Vio: Non-Inlineable methods (vio.c)
254  * @return  None
255  * @param   thee      Pointer to the Vio object
256  * @param   commChars comment character set
257  */
258 VEXTERNC void Vio_setCommChars(Vio *thee, char *commChars);
259 
260 /**
261  * @ingroup Vio
262  * @brief   Accept any waiting connect attempt to our socket on our machine
263  * @author  Michael Holst
264  * @note    Class Vio: Non-Inlineable methods (vio.c)
265  * @return  1 on success, -1 on failure
266  * @param   thee     Pointer to the Vio object
267  * @param   nonblock index for a non-blocking socket
268  *          Only for <UNIX/INET>; othewise it is ignored.
269  *          nonblock==0  ==> block until a connect is attempted
270  *          nonblock==1  ==> DO NOT block at all
271  */
272 VEXTERNC int Vio_accept(Vio *thee, int nonblock);
273 
274 /**
275  * @ingroup Vio
276  * @brief   Free the socket child that was used for the last accept
277  * @author  Michael Holst
278  * @note    Class Vio: Non-Inlineable methods (vio.c)
279  * @return  None
280  * @param   thee Pointer to the Vio object
281  */
282 VEXTERNC void Vio_acceptFree(Vio *thee);
283 
284 /**
285  * @ingroup Vio
286  * @brief   Connect to some socket on a remote machine (or on our machine)
287  * @author  Michael Holst
288  * @note    Class Vio: Non-Inlineable methods (vio.c)
289  * @return  1 on success, -1 on failure
290  * @param   thee     Pointer to the Vio object
291  * @param   nonblock index for a non-blocking socket
292  *          Only for <UNIX/INET>; othewise it is ignored.
293  *          nonblock==0  ==> block until a connect is attempted
294  *          nonblock==1  ==> DO NOT block at all
295  */
296 VEXTERNC int Vio_connect(Vio *thee, int nonblock);
297 
298 /**
299  * @ingroup Vio
300  * @brief   Purge any output buffers (for <UNIX/INET>, else a no-op)
301  * @author  Michael Holst
302  * @note    Class Vio: Non-Inlineable methods (vio.c)
303  * @return  None
304  * @param   thee Pointer to the Vio object
305  */
306 VEXTERNC void Vio_connectFree(Vio *thee);
307 
308 /**
309  * @ingroup Vio
310  * @brief   Mimic "scanf" from an arbitrary Vio device
311  * @author  Michael Holst
312  * @note    Class Vio: Non-Inlineable methods (vio.c)
313  * @return  Number of tokens read
314  * @param   thee  Pointer to the Vio object
315  * @param   parms Pointer to input parameters
316  */
317 VEXTERNC int Vio_scanf(Vio *thee, char *parms, ...);
318 
319 /**
320  * @ingroup Vio
321  * @brief   Mimic "printf" from an arbitrary Vio device
322  * @author  Michael Holst
323  * @note    Class Vio: Non-Inlineable methods (vio.c)
324  * @return  Number of tokens printed
325  * @param   thee  Pointer to the Vio object
326  * @param   parms Pointer to output parameters
327  */
328 VEXTERNC int Vio_printf(Vio *thee, char *parms, ...);
329 
330 /**
331  * @ingroup Vio
332  * @brief   Read (up to) bufsize characters into buf from input device
333  * @author  Michael Holst
334  * @note    Class Vio: Non-Inlineable methods (vio.c)
335  * @return  Number of bytes read
336  * @param   thee    Pointer to the Vio object
337  * @param   buf     buffer containing message
338  * @param   bufsize number of items (of declared type) in buffer
339  */
340 VEXTERNC int Vio_read(Vio *thee, char *buf, int bufsize);
341 
342 /**
343  * @ingroup Vio
344  * @brief   Write bufsize characters from buf to output device
345  * @author  Michael Holst
346  * @note    Class Vio: Non-Inlineable methods (vio.c)
347  * @return  Number of bytes writen
348  * @param   thee    Pointer to the Vio object
349  * @param   buf     buffer containing message
350  * @param   bufsize number of items (of declared type) in buffer
351  */
352 VEXTERNC int Vio_write(Vio *thee, char *buf, int bufsize);
353 
354 /**
355  * @ingroup Vio
356  * @brief   Set the pointer to the internal buffer
357  * @author  Michael Holst
358  * @note    Class Vio: Non-Inlineable methods (vio.c)
359  * @return  None
360  * @param   thee    Pointer to the Vio object
361  * @param   buf     buffer containing message
362  * @param   bufsize number of items (of declared type) in buffer
363  */
364 VEXTERNC void Vio_bufTake(Vio *thee, char *buf, int bufsize);
365 
366 /**
367  * @ingroup Vio
368  * @brief   Return the pointer to the internal buffer
369  * @author  Michael Holst
370  * @note    Class Vio: Non-Inlineable methods (vio.c)
371  * @return  Poitner to the internal buffer
372  * @param   thee Pointer to the Vio object
373  */
374 VEXTERNC char* Vio_bufGive(Vio *thee);
375 
376 /**
377  * @ingroup Vio
378  * @brief   Return the length to the internal buffer
379  * @author  Michael Holst
380  * @note    Class Vio: Non-Inlineable methods (vio.c)
381  * @return  Length of the internal buffer
382  * @param   thee Pointer to the Vio object
383  */
384 VEXTERNC int Vio_bufSize(Vio *thee);
385 
386 /**
387  * @ingroup Vio
388  * @brief   Socket open for read or write
389  * @author  Michael Holst
390  * @note    Class Vio: Non-Inlineable methods (vio.c)
391  * @return  Socket for reading/writing the external data
392  * @param   key    Pointer to the read/write option
393  * @param   iodev  Pointer to open device for read/write
394  * @param   iofmt  Pointer to i/o data format
395  * @param   iohost Pointer to i/o address of port
396  * @param   iofile Pointer to the i/o file name
397  */
398 VEXTERNC Vio *Vio_socketOpen(char *key,
399     const char *iodev, const char *iofmt,
400     const char *iohost, const char *iofile);
401 
402 /**
403  * @ingroup Vio
404  * @brief   Socket close from read or write
405  * @author  Michael Holst
406  * @note    Class Vio: Non-Inlineable methods (vio.c)
407  * @return  None
408  * @param   sock Socket for reading/writing the external data
409  */
410 VEXTERNC void Vio_socketClose(Vio **sock);
411 
412 #endif /* _VIO_H_ */
413 
414