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 * Set log file and Enable/disable logging of ADP packets to file.
98 void Adp_SetLogfile(const char *filename
);
99 void Adp_SetLogEnable(int logEnableFlag
);
102 * Function: Adp_OpenDevice
103 * Purpose: Open a device to use for channels communication. This is a
104 * very thin veneer to the device drivers: what hostchan.c
105 * will do is call DeviceMatch for each device driver until it
106 * finds a driver that will accept name and arg, then call
107 * DeviceOpen for that device.
109 * Pre-conditions: No previous open is still active
112 * Input: name Identifies which device to open. This can either be
113 * a host specific identifier (e.g. "/dev/ttya",
114 * "COM1:"), or a number which is used to refer to
115 * `standard' interfaces, so "1" would be the first host
116 * interface, "2" the second, and so on.
118 * arg Driver specific arguments. For example, some serial
119 * drivers accept speed and control arguments such as
120 * "9600" or "19200/NO_BREAK". These arguments are
121 * completely free-form: it is the individual drivers
122 * which do the necessary interpretation.
124 * heartbeat_on Incicates if the heartbeat is configured to be
125 * used or not, true if it is, false otherwise
129 * Error: adp_device_not_known,
130 * adp_device_open_failed
131 * adp_device_already_open
133 AdpErrs
Adp_OpenDevice(const char *name
, const char *arg
,
134 unsigned int heartbeat_on
);
137 * Function: Adp_CloseDevice
138 * Purpose: Close the device used for channels communication.
144 * Error: adp_device_not_open
146 AdpErrs
Adp_CloseDevice(void);
149 * Function: Adp_Ioctl
150 * Purpose: Perform miscellaneous control operations on
151 * the device used for channels communication.
152 * This is a minimal veneer to DevSW_Ioctl.
155 * Input: opcode Reason code indicating the operation to perform.
156 * In/Out: args Pointer to opcode-sensitive arguments/result space.
161 * Error: adp_device_not_open, adp_failed
163 AdpErrs
Adp_Ioctl(int opcode
, void *args
);
166 * Function: Adp_ChannelRegisterRead
167 * Purpose: Register a callback function for received packets on a given
171 * Input: chan The channel the callback function is for.
173 * cbfunc The callback function. If NULL, then the current
174 * callback is removed.
176 * cbstate State pointer to pass into the callback function
180 * Error: adp_device_not_open
183 * Post-conditions: The callback function is responsible for freeing the
184 * packet that is passed to it, when that packet is
192 extern AdpErrs
Adp_ChannelRegisterRead(const ChannelID chan
,
193 const ChannelCallback cbfunc
,
200 * Function: Adp_ChannelRead
201 * Purpose: Wait until a packet has been read for a given channel, and
202 * then return it. Callbacks for other channels are still
203 * active while this read is blocking.
205 * Pre-conditions: No callback has been already been registered for
209 * Input: chan The channel to read.
211 * Output: packet The received packet.
215 * Error: adp_device_not_open
217 * adp_callback_already_registered
219 * Post-conditions: The calling function is responsible for freeing the
220 * received packet, when that packet is no longer
223 AdpErrs
Adp_ChannelRead(const ChannelID chan
, Packet
**packet
);
226 * Function: Adp_ChannelWrite
227 * Purpose: Write a packet to the given channel
229 * Pre-conditions: Channel must have been previously opened.
232 * Input: chan The channel to write.
234 * packet The packet to write.
238 * Error: adp_device_not_open
241 * Post-conditions: The packet being written becomes the "property" of
242 * Adp_ChannelWrite, which is responsible for freeing
243 * the packet when it is no longer needed.
245 AdpErrs
Adp_ChannelWrite(const ChannelID chan
, Packet
*packet
);
248 * Function: Adp_ChannelWriteAsync
249 * Purpose: Write a packet to the given channel, but don't wait
250 * for the write to complete before returning.
252 * Pre-conditions: Channel must have been previously opened.
255 * Input: chan The channel to write.
257 * packet The packet to write.
261 * Error: adp_device_not_open
264 * Post-conditions: The packet being written becomes the "property" of
265 * Adp_ChannelWrite, which is responsible for freeing
266 * the packet when it is no longer needed.
268 AdpErrs
Adp_ChannelWriteAsync(const ChannelID chan
, Packet
*packet
);
271 * Function: Adp_AsynchronousProcessing
272 * Purpose: This routine should be called from persistent any idle loop
273 * to give the data I/O routines a chance to poll for packet
274 * activity. Depending upon the requested mode, this routine
275 * may, or may not, block.
278 * Input: mode Specifies whether to block until a complete packet
279 * has been read, all pending writes have completed,
280 * or not to block at all.
284 void Adp_AsynchronousProcessing(const AsyncMode mode
);
287 * prototype for DC_APPL packet handler
289 typedef void (*DC_Appl_Handler
)(const DeviceDescr
*device
, Packet
*packet
);
292 * install a handler for DC_APPL packets (can be NULL), returning old one.
294 DC_Appl_Handler
Adp_Install_DC_Appl_Handler(const DC_Appl_Handler handler
);
297 * prototype for asynchronous processing callback
299 typedef void (*Adp_Async_Callback
)(const DeviceDescr
*device
,
300 const struct timeval
*const time_now
);
303 * add an asynchronous processing callback to the list
304 * TRUE == okay, FALSE == no more async processing slots
306 bool Adp_Install_Async_Callback( const Adp_Async_Callback callback_proc
);
309 * delay for a given period (in microseconds)
311 void Adp_delay(unsigned int period
);
313 #endif /* ndef angsd_hostchan_h */