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