1/*
2 * Copyright (C) 1995 Advanced RISC Machines Limited. All rights reserved.
3 *
4 * This software may be freely used, copied, modified, and distributed
5 * provided that the above copyright notice is preserved in all copies of the
6 * software.
7 */
8
9/* -*-C-*-
10 *
11 * $Revision: 1.3 $
12 *     $Date: 2004/12/27 14:00:54 $
13 *
14 */
15#ifndef angsd_hostchan_h
16#define angsd_hostchan_h
17
18/* A temporary sop to older compilers */
19#if defined (__NetBSD__) || defined (unix)
20#  ifndef __unix              /* (good for long-term portability?)  */
21#    define __unix    1
22#  endif
23#endif
24
25/* struct timeval */
26#if defined(__unix) || defined(__CYGWIN__)
27#  include <sys/time.h>
28#else
29#  include "winsock.h"
30#  include "time.h"
31#endif
32
33#include "chandefs.h"
34#include "adperr.h"
35#include "devsw.h"
36
37/*
38 * asynchronous processing modes
39 */
40enum AsyncMode
41{
42    async_block_on_nothing,
43    async_block_on_read,
44    async_block_on_write
45};
46
47#ifndef __cplusplus
48typedef enum AsyncMode AsyncMode;
49#endif
50
51/*
52 * prototype for channels callback function
53 */
54typedef void (*ChannelCallback)(Packet *packet, void *state);
55
56/*
57 *  Function: Adp_initSeq
58 *   Purpose: initialise the channel protocol and sequence numbers
59 *
60 *    Params: none
61 *
62 *   Returns: Nothing
63 */
64extern void Adp_initSeq(void);
65
66/*
67 *  Function: Adp_addToQueue
68 *   Purpose: chain a Packet to the end of a linked list of such structures
69 *
70 *    Params:
71 *      In/Out: head    Head of the linked list
72 *
73 *              newpkt  Packet to be chained onto the list
74 *
75 *   Returns: Nothing
76 */
77extern void Adp_addToQueue(Packet **head, Packet *newpkt);
78
79/*
80 *  Function: removeFromQueue
81 *   Purpose: remove a Packet from the head of a linked list of such structures
82 *
83 *    Params:
84 *      In/Out: head    Head of the linked list
85 *
86 *   Returns: Old head from the linked list
87 *
88 * Post-conditions: Second element in the list will be the new head.
89 */
90
91extern Packet *Adp_removeFromQueue(Packet **head);
92
93/*
94 * Set log file and Enable/disable logging of ADP packets to file.
95 */
96
97void Adp_SetLogfile(const char *filename);
98void Adp_SetLogEnable(int logEnableFlag);
99
100/*
101 *  Function: Adp_OpenDevice
102 *   Purpose: Open a device to use for channels communication.  This is a
103 *              very thin veneer to the device drivers: what hostchan.c
104 *              will do is call DeviceMatch for each device driver until it
105 *              finds a driver that will accept name and arg, then call
106 *              DeviceOpen for that device.
107 *
108 *  Pre-conditions: No previous open is still active
109 *
110 *    Params:
111 *       Input: name    Identifies which device to open.  This can either be
112 *                      a host specific identifier (e.g. "/dev/ttya",
113 *                      "COM1:"), or a number which is used to refer to
114 *                      `standard' interfaces, so "1" would be the first host
115 *                      interface, "2" the second, and so on.
116 *
117 *              arg     Driver specific arguments.  For example, some serial
118 *                      drivers accept speed and control arguments such as
119 *                      "9600" or "19200/NO_BREAK".  These arguments are
120 *                      completely free-form: it is the individual drivers
121 *                      which do the necessary interpretation.
122 *
123 *              heartbeat_on  Incicates if the heartbeat is configured to be
124 *                      used or not, true if it is, false otherwise
125 *
126 *   Returns:
127 *          OK: adp_ok
128 *       Error: adp_device_not_known,
129 *              adp_device_open_failed
130 *              adp_device_already_open
131 */
132AdpErrs Adp_OpenDevice(const char *name, const char *arg,
133                       unsigned int heartbeat_on);
134
135/*
136 *  Function: Adp_CloseDevice
137 *   Purpose: Close the device used for channels communication.
138 *
139 *    Params: None
140 *
141 *   Returns:
142 *          OK: adp_ok
143 *       Error: adp_device_not_open
144 */
145AdpErrs Adp_CloseDevice(void);
146
147/*
148 *  Function: Adp_Ioctl
149 *   Purpose: Perform miscellaneous control operations on
150 *              the device used for channels communication.
151 *              This is a minimal veneer to DevSW_Ioctl.
152 *
153 *    Params:
154 *       Input: opcode  Reason code indicating the operation to perform.
155 *      In/Out: args    Pointer to opcode-sensitive arguments/result space.
156 *
157 *
158 *   Returns:
159 *          OK: adp_ok
160 *       Error: adp_device_not_open, adp_failed
161 */
162AdpErrs Adp_Ioctl(int opcode, void *args);
163
164/*
165 *  Function: Adp_ChannelRegisterRead
166 *   Purpose: Register a callback function for received packets on a given
167 *              channel
168 *
169 *    Params:
170 *       Input: chan    The channel the callback function is for.
171 *
172 *              cbfunc  The callback function.  If NULL, then the current
173 *                      callback is removed.
174 *
175 *              cbstate State pointer to pass into the callback function
176 *
177 *   Returns:
178 *          OK: adp_ok
179 *       Error: adp_device_not_open
180 *              adp_bad_channel_id
181 *
182 * Post-conditions: The callback function is responsible for freeing the
183 *                      packet that is passed to it, when that packet is
184 *                      no longer needed.
185 */
186#ifdef __cplusplus
187    extern "C" {
188#endif
189
190
191extern AdpErrs Adp_ChannelRegisterRead(const ChannelID chan,
192                               const ChannelCallback cbfunc,
193                                void *cbstate);
194
195#ifdef __cplusplus
196    }
197#endif
198/*
199 *  Function: Adp_ChannelRead
200 *   Purpose: Wait until a packet has been read for a given channel, and
201 *              then return it.  Callbacks for other channels are still
202 *              active while this read is blocking.
203 *
204 *  Pre-conditions: No callback has been already been registered for
205 *                      the channel.
206 *
207 *    Params:
208 *       Input: chan    The channel to read.
209 *
210 *      Output: packet  The received packet.
211 *
212 *   Returns:
213 *          OK: adp_ok
214 *       Error: adp_device_not_open
215 *              adp_bad_channel_id
216 *              adp_callback_already_registered
217 *
218 * Post-conditions: The calling function is responsible for freeing the
219 *                      received packet, when that packet is no longer
220 *                      needed.
221 */
222AdpErrs Adp_ChannelRead(const ChannelID chan, Packet **packet);
223
224/*
225 *  Function: Adp_ChannelWrite
226 *   Purpose: Write a packet to the given channel
227 *
228 *  Pre-conditions: Channel must have been previously opened.
229 *
230 *    Params:
231 *       Input: chan    The channel to write.
232 *
233 *              packet  The packet to write.
234 *
235 *   Returns:
236 *          OK: adp_ok
237 *       Error: adp_device_not_open
238 *              adp_bad_channel_id
239 *
240 * Post-conditions: The packet being written becomes the "property" of
241 *                      Adp_ChannelWrite, which is responsible for freeing
242 *                      the packet when it is no longer needed.
243 */
244AdpErrs Adp_ChannelWrite(const ChannelID chan, Packet *packet);
245
246/*
247 *  Function: Adp_ChannelWriteAsync
248 *   Purpose: Write a packet to the given channel, but don't wait
249 *            for the write to complete before returning.
250 *
251 *  Pre-conditions: Channel must have been previously opened.
252 *
253 *    Params:
254 *       Input: chan    The channel to write.
255 *
256 *              packet  The packet to write.
257 *
258 *   Returns:
259 *          OK: adp_ok
260 *       Error: adp_device_not_open
261 *              adp_bad_channel_id
262 *
263 * Post-conditions: The packet being written becomes the "property" of
264 *                      Adp_ChannelWrite, which is responsible for freeing
265 *                      the packet when it is no longer needed.
266 */
267AdpErrs Adp_ChannelWriteAsync(const ChannelID chan, Packet *packet);
268
269/*
270 *  Function: Adp_AsynchronousProcessing
271 *   Purpose: This routine should be called from persistent any idle loop
272 *              to give the data I/O routines a chance to poll for packet
273 *              activity.  Depending upon the requested mode, this routine
274 *              may, or may not, block.
275 *
276 *    Params:
277 *       Input: mode    Specifies whether to block until a complete packet
278 *                      has been read, all pending writes have completed,
279 *                      or not to block at all.
280 *
281 *   Returns: Nothing.
282 */
283void Adp_AsynchronousProcessing(const AsyncMode mode);
284
285/*
286 * prototype for DC_APPL packet handler
287 */
288typedef void (*DC_Appl_Handler)(const DeviceDescr *device, Packet *packet);
289
290/*
291 * install a handler for DC_APPL packets (can be NULL), returning old one.
292 */
293DC_Appl_Handler Adp_Install_DC_Appl_Handler(const DC_Appl_Handler handler);
294
295/*
296 * prototype for asynchronous processing callback
297 */
298typedef void (*Adp_Async_Callback)(const DeviceDescr *device,
299                                   const struct timeval *const time_now);
300
301/*
302 * add an asynchronous processing callback to the list
303 * TRUE == okay, FALSE == no more async processing slots
304 */
305bool Adp_Install_Async_Callback( const Adp_Async_Callback callback_proc );
306
307/*
308 * delay for a given period (in microseconds)
309 */
310void Adp_delay(unsigned int period);
311
312#endif /* ndef angsd_hostchan_h */
313
314/* EOF hostchan.h */
315