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. */
26 /* A temporary sop to older compilers */
27 #if defined (__NetBSD__) || defined (unix)
28 # ifndef __unix /* (good for long-term portability?) */
34 #if defined(__unix) || defined(__CYGWIN32__)
35 # include <sys/time.h>
46 * asynchronous processing modes
50 async_block_on_nothing
,
56 typedef enum AsyncMode AsyncMode
;
60 * prototype for channels callback function
62 typedef void (*ChannelCallback
)(Packet
*packet
, void *state
);
65 * Function: Adp_initSeq
66 * Purpose: initialise the channel protocol and sequence numbers
72 extern void Adp_initSeq(void);
75 * Function: Adp_addToQueue
76 * Purpose: chain a Packet to the end of a linked list of such structures
79 * In/Out: head Head of the linked list
81 * newpkt Packet to be chained onto the list
85 extern void Adp_addToQueue(Packet
**head
, Packet
*newpkt
);
88 * Function: removeFromQueue
89 * Purpose: remove a Packet from the head of a linked list of such structures
92 * In/Out: head Head of the linked list
94 * Returns: Old head from the linked list
96 * Post-conditions: Second element in the list will be the new head.
99 extern Packet
*Adp_removeFromQueue(Packet
**head
);
102 * Set log file and Enable/disable logging of ADP packets to file.
105 void Adp_SetLogfile(const char *filename
);
106 void Adp_SetLogEnable(int logEnableFlag
);
109 * Function: Adp_OpenDevice
110 * Purpose: Open a device to use for channels communication. This is a
111 * very thin veneer to the device drivers: what hostchan.c
112 * will do is call DeviceMatch for each device driver until it
113 * finds a driver that will accept name and arg, then call
114 * DeviceOpen for that device.
116 * Pre-conditions: No previous open is still active
119 * Input: name Identifies which device to open. This can either be
120 * a host specific identifier (e.g. "/dev/ttya",
121 * "COM1:"), or a number which is used to refer to
122 * `standard' interfaces, so "1" would be the first host
123 * interface, "2" the second, and so on.
125 * arg Driver specific arguments. For example, some serial
126 * drivers accept speed and control arguments such as
127 * "9600" or "19200/NO_BREAK". These arguments are
128 * completely free-form: it is the individual drivers
129 * which do the necessary interpretation.
131 * heartbeat_on Incicates if the heartbeat is configured to be
132 * used or not, true if it is, false otherwise
136 * Error: adp_device_not_known,
137 * adp_device_open_failed
138 * adp_device_already_open
140 AdpErrs
Adp_OpenDevice(const char *name
, const char *arg
,
141 unsigned int heartbeat_on
);
144 * Function: Adp_CloseDevice
145 * Purpose: Close the device used for channels communication.
151 * Error: adp_device_not_open
153 AdpErrs
Adp_CloseDevice(void);
156 * Function: Adp_Ioctl
157 * Purpose: Perform miscellaneous control operations on
158 * the device used for channels communication.
159 * This is a minimal veneer to DevSW_Ioctl.
162 * Input: opcode Reason code indicating the operation to perform.
163 * In/Out: args Pointer to opcode-sensitive arguments/result space.
168 * Error: adp_device_not_open, adp_failed
170 AdpErrs
Adp_Ioctl(int opcode
, void *args
);
173 * Function: Adp_ChannelRegisterRead
174 * Purpose: Register a callback function for received packets on a given
178 * Input: chan The channel the callback function is for.
180 * cbfunc The callback function. If NULL, then the current
181 * callback is removed.
183 * cbstate State pointer to pass into the callback function
187 * Error: adp_device_not_open
190 * Post-conditions: The callback function is responsible for freeing the
191 * packet that is passed to it, when that packet is
199 extern AdpErrs
Adp_ChannelRegisterRead(const ChannelID chan
,
200 const ChannelCallback cbfunc
,
207 * Function: Adp_ChannelRead
208 * Purpose: Wait until a packet has been read for a given channel, and
209 * then return it. Callbacks for other channels are still
210 * active while this read is blocking.
212 * Pre-conditions: No callback has been already been registered for
216 * Input: chan The channel to read.
218 * Output: packet The received packet.
222 * Error: adp_device_not_open
224 * adp_callback_already_registered
226 * Post-conditions: The calling function is responsible for freeing the
227 * received packet, when that packet is no longer
230 AdpErrs
Adp_ChannelRead(const ChannelID chan
, Packet
**packet
);
233 * Function: Adp_ChannelWrite
234 * Purpose: Write a packet to the given channel
236 * Pre-conditions: Channel must have been previously opened.
239 * Input: chan The channel to write.
241 * packet The packet to write.
245 * Error: adp_device_not_open
248 * Post-conditions: The packet being written becomes the "property" of
249 * Adp_ChannelWrite, which is responsible for freeing
250 * the packet when it is no longer needed.
252 AdpErrs
Adp_ChannelWrite(const ChannelID chan
, Packet
*packet
);
255 * Function: Adp_ChannelWriteAsync
256 * Purpose: Write a packet to the given channel, but don't wait
257 * for the write to complete before returning.
259 * Pre-conditions: Channel must have been previously opened.
262 * Input: chan The channel to write.
264 * packet The packet to write.
268 * Error: adp_device_not_open
271 * Post-conditions: The packet being written becomes the "property" of
272 * Adp_ChannelWrite, which is responsible for freeing
273 * the packet when it is no longer needed.
275 AdpErrs
Adp_ChannelWriteAsync(const ChannelID chan
, Packet
*packet
);
278 * Function: Adp_AsynchronousProcessing
279 * Purpose: This routine should be called from persistent any idle loop
280 * to give the data I/O routines a chance to poll for packet
281 * activity. Depending upon the requested mode, this routine
282 * may, or may not, block.
285 * Input: mode Specifies whether to block until a complete packet
286 * has been read, all pending writes have completed,
287 * or not to block at all.
291 void Adp_AsynchronousProcessing(const AsyncMode mode
);
294 * prototype for DC_APPL packet handler
296 typedef void (*DC_Appl_Handler
)(const DeviceDescr
*device
, Packet
*packet
);
299 * install a handler for DC_APPL packets (can be NULL), returning old one.
301 DC_Appl_Handler
Adp_Install_DC_Appl_Handler(const DC_Appl_Handler handler
);
304 * prototype for asynchronous processing callback
306 typedef void (*Adp_Async_Callback
)(const DeviceDescr
*device
,
307 const struct timeval
*const time_now
);
310 * add an asynchronous processing callback to the list
311 * TRUE == okay, FALSE == no more async processing slots
313 bool Adp_Install_Async_Callback( const Adp_Async_Callback callback_proc
);
316 * delay for a given period (in microseconds)
318 void Adp_delay(unsigned int period
);
320 #endif /* ndef angsd_hostchan_h */