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
19 #if defined(__unix) || defined(__CYGWIN32__)
20 # include <sys/time.h>
31 * asynchronous processing modes
35 async_block_on_nothing
,
41 typedef enum AsyncMode AsyncMode
;
45 * prototype for channels callback function
47 typedef void (*ChannelCallback
)(Packet
*packet
, void *state
);
50 * Function: Adp_initSeq
51 * Purpose: initialise the channel protocol and sequence numbers
57 extern void Adp_initSeq(void);
60 * Function: Adp_addToQueue
61 * Purpose: chain a Packet to the end of a linked list of such structures
64 * In/Out: head Head of the linked list
66 * newpkt Packet to be chained onto the list
70 extern void Adp_addToQueue(Packet
**head
, Packet
*newpkt
);
73 * Function: removeFromQueue
74 * Purpose: remove a Packet from the head of a linked list of such structures
77 * In/Out: head Head of the linked list
79 * Returns: Old head from the linked list
81 * Post-conditions: Second element in the list will be the new head.
84 extern Packet
*Adp_removeFromQueue(Packet
**head
);
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.
94 * Pre-conditions: No previous open is still active
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.
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.
109 * heartbeat_on Incicates if the heartbeat is configured to be
110 * used or not, true if it is, false otherwise
114 * Error: adp_device_not_known,
115 * adp_device_open_failed
116 * adp_device_already_open
118 AdpErrs
Adp_OpenDevice(const char *name
, const char *arg
,
119 unsigned int heartbeat_on
);
122 * Function: Adp_CloseDevice
123 * Purpose: Close the device used for channels communication.
129 * Error: adp_device_not_open
131 AdpErrs
Adp_CloseDevice(void);
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.
140 * Input: opcode Reason code indicating the operation to perform.
141 * In/Out: args Pointer to opcode-sensitive arguments/result space.
146 * Error: adp_device_not_open, adp_failed
148 AdpErrs
Adp_Ioctl(int opcode
, void *args
);
151 * Function: Adp_ChannelRegisterRead
152 * Purpose: Register a callback function for received packets on a given
156 * Input: chan The channel the callback function is for.
158 * cbfunc The callback function. If NULL, then the current
159 * callback is removed.
161 * cbstate State pointer to pass into the callback function
165 * Error: adp_device_not_open
168 * Post-conditions: The callback function is responsible for freeing the
169 * packet that is passed to it, when that packet is
177 extern AdpErrs
Adp_ChannelRegisterRead(const ChannelID chan
,
178 const ChannelCallback cbfunc
,
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.
190 * Pre-conditions: No callback has been already been registered for
194 * Input: chan The channel to read.
196 * Output: packet The received packet.
200 * Error: adp_device_not_open
202 * adp_callback_already_registered
204 * Post-conditions: The calling function is responsible for freeing the
205 * received packet, when that packet is no longer
208 AdpErrs
Adp_ChannelRead(const ChannelID chan
, Packet
**packet
);
211 * Function: Adp_ChannelWrite
212 * Purpose: Write a packet to the given channel
214 * Pre-conditions: Channel must have been previously opened.
217 * Input: chan The channel to write.
219 * packet The packet to write.
223 * Error: adp_device_not_open
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.
230 AdpErrs
Adp_ChannelWrite(const ChannelID chan
, Packet
*packet
);
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.
237 * Pre-conditions: Channel must have been previously opened.
240 * Input: chan The channel to write.
242 * packet The packet to write.
246 * Error: adp_device_not_open
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.
253 AdpErrs
Adp_ChannelWriteAsync(const ChannelID chan
, Packet
*packet
);
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.
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.
269 void Adp_AsynchronousProcessing(const AsyncMode mode
);
272 * prototype for DC_APPL packet handler
274 typedef void (*DC_Appl_Handler
)(const DeviceDescr
*device
, Packet
*packet
);
277 * install a handler for DC_APPL packets (can be NULL), returning old one.
279 DC_Appl_Handler
Adp_Install_DC_Appl_Handler(const DC_Appl_Handler handler
);
282 * prototype for asynchronous processing callback
284 typedef void (*Adp_Async_Callback
)(const DeviceDescr
*device
,
285 const struct timeval
*const time_now
);
288 * add an asynchronous processing callback to the list
289 * TRUE == okay, FALSE == no more async processing slots
291 bool Adp_Install_Async_Callback( const Adp_Async_Callback callback_proc
);
294 * delay for a given period (in microseconds)
296 void Adp_delay(unsigned int period
);
298 #endif /* ndef angsd_hostchan_h */