2 * Copyright (C) 1995 Advanced RISC Machines Limited. All rights reserved.
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
15 #ifndef angsd_hostchan_h
16 #define angsd_hostchan_h
18 /* If under Cygwin, provide backwards compatibility with older
19 Cygwin compilers that don't define the current cpp define. */
27 #if defined(__unix) || defined(__CYGWIN32__)
28 # include <sys/time.h>
39 * asynchronous processing modes
43 async_block_on_nothing
,
49 typedef enum AsyncMode AsyncMode
;
53 * prototype for channels callback function
55 typedef void (*ChannelCallback
)(Packet
*packet
, void *state
);
58 * Function: Adp_initSeq
59 * Purpose: initialise the channel protocol and sequence numbers
65 extern void Adp_initSeq(void);
68 * Function: Adp_addToQueue
69 * Purpose: chain a Packet to the end of a linked list of such structures
72 * In/Out: head Head of the linked list
74 * newpkt Packet to be chained onto the list
78 extern void Adp_addToQueue(Packet
**head
, Packet
*newpkt
);
81 * Function: removeFromQueue
82 * Purpose: remove a Packet from the head of a linked list of such structures
85 * In/Out: head Head of the linked list
87 * Returns: Old head from the linked list
89 * Post-conditions: Second element in the list will be the new head.
92 extern Packet
*Adp_removeFromQueue(Packet
**head
);
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.
102 * Pre-conditions: No previous open is still active
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.
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.
117 * heartbeat_on Incicates if the heartbeat is configured to be
118 * used or not, true if it is, false otherwise
122 * Error: adp_device_not_known,
123 * adp_device_open_failed
124 * adp_device_already_open
126 AdpErrs
Adp_OpenDevice(const char *name
, const char *arg
,
127 unsigned int heartbeat_on
);
130 * Function: Adp_CloseDevice
131 * Purpose: Close the device used for channels communication.
137 * Error: adp_device_not_open
139 AdpErrs
Adp_CloseDevice(void);
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.
148 * Input: opcode Reason code indicating the operation to perform.
149 * In/Out: args Pointer to opcode-sensitive arguments/result space.
154 * Error: adp_device_not_open, adp_failed
156 AdpErrs
Adp_Ioctl(int opcode
, void *args
);
159 * Function: Adp_ChannelRegisterRead
160 * Purpose: Register a callback function for received packets on a given
164 * Input: chan The channel the callback function is for.
166 * cbfunc The callback function. If NULL, then the current
167 * callback is removed.
169 * cbstate State pointer to pass into the callback function
173 * Error: adp_device_not_open
176 * Post-conditions: The callback function is responsible for freeing the
177 * packet that is passed to it, when that packet is
185 extern AdpErrs
Adp_ChannelRegisterRead(const ChannelID chan
,
186 const ChannelCallback cbfunc
,
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.
198 * Pre-conditions: No callback has been already been registered for
202 * Input: chan The channel to read.
204 * Output: packet The received packet.
208 * Error: adp_device_not_open
210 * adp_callback_already_registered
212 * Post-conditions: The calling function is responsible for freeing the
213 * received packet, when that packet is no longer
216 AdpErrs
Adp_ChannelRead(const ChannelID chan
, Packet
**packet
);
219 * Function: Adp_ChannelWrite
220 * Purpose: Write a packet to the given channel
222 * Pre-conditions: Channel must have been previously opened.
225 * Input: chan The channel to write.
227 * packet The packet to write.
231 * Error: adp_device_not_open
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.
238 AdpErrs
Adp_ChannelWrite(const ChannelID chan
, Packet
*packet
);
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.
245 * Pre-conditions: Channel must have been previously opened.
248 * Input: chan The channel to write.
250 * packet The packet to write.
254 * Error: adp_device_not_open
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.
261 AdpErrs
Adp_ChannelWriteAsync(const ChannelID chan
, Packet
*packet
);
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.
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.
277 void Adp_AsynchronousProcessing(const AsyncMode mode
);
280 * prototype for DC_APPL packet handler
282 typedef void (*DC_Appl_Handler
)(const DeviceDescr
*device
, Packet
*packet
);
285 * install a handler for DC_APPL packets (can be NULL), returning old one.
287 DC_Appl_Handler
Adp_Install_DC_Appl_Handler(const DC_Appl_Handler handler
);
290 * prototype for asynchronous processing callback
292 typedef void (*Adp_Async_Callback
)(const DeviceDescr
*device
,
293 const struct timeval
*const time_now
);
296 * add an asynchronous processing callback to the list
297 * TRUE == okay, FALSE == no more async processing slots
299 bool Adp_Install_Async_Callback( const Adp_Async_Callback callback_proc
);
302 * delay for a given period (in microseconds)
304 void Adp_delay(unsigned int period
);
306 #endif /* ndef angsd_hostchan_h */