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