source: pacpussensors/trunk/CanGateway/driver/kvaser/windows/j1587lib.h@ 134

Last change on this file since 134 was 93, checked in by DHERBOMEZ Gérald, 9 years ago

move files in windows folder
File size: 14.4 KB
Line 
1/**
2 * \section LICENSE
3 * Copyright 2007-2011 by KVASER AB, SWEDEN
4 *
5 * WWW: http://www.kvaser.com
6 *
7 * This software is furnished under a license and may be used and copied
8 * only in accordance with the terms of such license.
9 *
10 * \section DESCRIPTION
11 *
12 * Definitions for the J1587lib API.
13 *
14 * \file j1587lib.h
15 * \author Kvaser AB
16 */
17
18
19#ifndef __J1587LIB_H
20#define __J1587LIB_H
21
22/**
23 * \defgroup J1587 J1587
24 * @{
25 */
26
27#include <windows.h>
28
29/**
30 * J1587 handle
31 */
32typedef int J1587Handle;
33
34/**
35 * Invalid J1587 handle
36 */
37#define j1587INVALID_HANDLE ((J1587Handle)(-1))
38
39/**
40 * \name Linx tranceiver types
41 * \anchor canTRANSCEIVER_TYPE_LINX_xxx
42 * @{
43 */
44#define canTRANSCEIVER_TYPE_LINX_LIN 64
45#define canTRANSCEIVER_TYPE_LINX_J1708 66
46#define canTRANSCEIVER_TYPE_LINX_K 68
47#define canTRANSCEIVER_TYPE_LINX_SWC 70
48#define canTRANSCEIVER_TYPE_LINX_LS 72
49/** @} */
50
51/**
52 * \name Operation modes
53 * \anchor EEPROM_OP_MODE_xxx
54 * @{
55 */
56#define EEPROM_OP_MODE_NONE 0x00
57#define EEPROM_OP_MODE_J1587_NORMAL 0x01
58#define EEPROM_OP_MODE_J1587_NODE 0x02
59/** @} */
60
61/**
62 * \name Flags for J1587MessageInfo
63 * \anchor j1587FLAG_xxx
64 * @{
65 */
66#define j1587FLAG_CHECKSUM 0x80
67#define j1587FLAG_FRAMEDELAY 0x40
68#define j1587FLAG_BYTEDELAY 0x20
69#define j1587FLAG_STOPBIT 0x10
70#define j1587FLAG_OVERRUN 0x08
71/** @} */
72
73/**
74 * \name Return codes from the J1587lib functions
75 * \anchor j1587ERR_xxx
76 * @{
77 */
78typedef enum {
79 j1587OK = 0, ///< OK - no error
80 j1587ERR_NOMSG = -1, ///< No messages available
81 j1587ERR_NOTRUNNING = -3,
82 j1587ERR_RUNNING = -4,
83 j1587ERR_NORMALONLY = -5,
84 j1587ERR_NODEONLY = -6,
85 j1587ERR_PARAM = -7, ///< Error in parameter
86 j1587ERR_NOTFOUND = -8, ///< Specified hw not found.
87 j1587ERR_NOMEM = -9, ///< Out of memory
88 j1587ERR_NOCHANNELS = -10, ///< No channels avaliable
89 j1587ERR_TIMEOUT = -11, ///< Timeout occurred
90 j1587ERR_NOTINITIALIZED = -12, ///< Library not initialized
91 j1587ERR_NOHANDLES = -13, ///< Can't get handle
92 j1587ERR_INVHANDLE = -14, ///< Handle is invalid
93 j1587ERR_CANERROR = -15,
94 j1587ERR_ERRRESP = -16, ///< There was an error response from the J1587 interface
95 j1587ERR_WRONGRESP = -17, ///< The J1587 interface response wasn't the expected one
96 j1587ERR_DRIVER = -18, ///< CAN driver type not supported
97 j1587ERR_DRIVERFAILED = -19, ///< DeviceIOControl failed; use Win32 GetLastError()
98 j1587ERR_NOCARD = -20, ///< The card was removed or not inserted
99 j1587ERR_LICENSE = -21, ///< The license is not valid.
100 j1587ERR_INTERNAL = -22, ///< Internal error in the driver.
101 j1587ERR_NO_ACCESS = -23, ///< Access denied
102 j1587ERR_VERSION = -24 ///< Function not supported in this version.
103} J1587Status;
104/** @} */
105
106/**
107 * J1587 library version definition
108 */
109#define J1587LIB_VERSION 1
110
111// sizeof(J1587MessageInfo) should be 16
112#include <pshpack1.h>
113
114
115
116/**
117 * \name J1587MessageInfo
118 * \anchor J1587MessageInfo
119 *
120 * In certain J1587 bus API calls, the following structure is used to provide
121 * more information about the J1587 messages.
122 */
123typedef struct {
124 /**
125 * To enable future extensions of this structure (see J1587LIB_VERSION).
126 */
127 unsigned char version;
128
129 /**
130 * Miscellaneous flags
131 */
132 unsigned char flags;
133
134 /**
135 * Frame delay in bit times (up to 255).
136 * - Read: Length of inter-frame delay.
137 * - Write: Delay before message transmission could begin.
138 */
139 unsigned char frameDelay;
140
141 union {
142 /**
143 * Checksum as read from the J1587 bus. Might not
144 * match the data in case of J1587_CSUM_ERROR.
145 */
146 unsigned char checkSum;
147 /**
148 * Number of retries before message could be transmitted.
149 */
150 unsigned char retries;
151 };
152
153 /**
154 * Timestamp in ms of the reception/transmission completion
155 * of the checksum. Uses the canlib CAN timer.
156 */
157 unsigned long timestamp;
158
159 /**
160 * Total frame length in microseconds;
161 * from the first start bit to the end of the checksum.
162 */
163 unsigned long frameLength;
164
165 /**
166 * Bitrate of the message in bits per second.
167 * Range [1000 .. 60000] (plus some margin)
168 */
169 unsigned short bitrate;
170
171 /**
172 * Reserved
173 */
174 unsigned short reserved;
175} J1587MessageInfo;
176#include <poppack.h>
177
178
179// Define J1587LIBAPI unless it's done already.
180// (j1587lib.c provides its own definition of J1587LIBAPI before including this file.)
181//
182#ifndef J1587LIBAPI
183# if defined(__BORLANDC__)
184# define J1587LIBAPI __stdcall
185# elif defined(_MSC_VER) || defined(__MWERKS__) || defined(__GNUC__)
186# define J1587LIBAPI __stdcall
187# endif
188#endif
189
190#ifdef __cplusplus
191extern "C" {
192#endif
193
194/**
195 * To be called before the library is used.
196 */
197void J1587LIBAPI j1587InitializeLibrary(void);
198
199
200/**
201 * Open a channel to a J1587 interface.
202 *
203 * \note The J1587 cable must be powered.
204 *
205 * The channel number is the same that
206 * is used by \ref canOpenChannel() to access the LAPcan channel.
207 *
208 * \param[in] channel The number of the channel. This is the same as used
209 * by \ref canOpenChannel() to access the LAPcan channel.
210 * \param[in] flags Flags of type \ref J1587_xxx
211 *
212 * \return If the call succeeds, a handle to the opened channel is returned.
213 * The handle is an integer greater than or equal to zero.
214 *
215 * \return If the call fails, the return value is a negative integer indicating
216 * an error code. See \ref j1587ERR_xxx for a list of possible error codes.
217 *
218 * \sa \ref j1587Close()
219 */
220J1587Handle J1587LIBAPI j1587OpenChannel(int channel, int flags);
221
222/**
223 * \name Flags for j1587OpenChannel()
224 * \anchor J1587_xxx
225 * @{
226 */
227#define J1587_NORMAL 1
228#define J1587_NODE 2
229#define J1587_READ 4
230#define J1587_WRITE 8
231/** @} */
232
233/**
234 * Closes an open handle to a J1587 channel. The handle becomes invalid and can
235 * not be used in subsequent calls to the J1587 functions.
236 *
237 * \param[in] h A handle to an open J1587 channel.
238 *
239 * \return \ref j1587OK (zero) if success
240 * \return \ref j1587ERR_xxx (negative) if failure
241 *
242 * \sa \ref j1587OpenChannel()
243 */
244J1587Status J1587LIBAPI j1587Close(J1587Handle h);
245
246/**
247 * This function retrieves the firmware version from the J1587 interface.
248 *
249 *
250 * \note The version numbers aren't valid until \ref j1587BusOn() has been called.
251 *
252 * \note The firmware in the J1587 interface is divided into two parts, the boot
253 * code and the application. The boot code is used only when reprogramming
254 * (reflashing) the J1597 interface. The application handles all J1587 communication.
255 *
256 * \note Version numbers are, since the precambric era, divided into a major
257 * version number, a minor version number and a build number. These are usually
258 * written like, for example, 3.2.12. Here the major number is 3, the minor
259 * number 2 and the build number 12.
260 *
261 * \param[in] h A handle to an open J1587 channel.
262 * \param[out] bootVerMajor A pointer to a byte where the major version number
263 * of the boot code is stored.
264 * \param[out] bootVerMinor A pointer to a byte where the minor version number
265 * of the boot code is stored.
266 * \param[out] bootVerBuild A pointer to a byte where the build number of the
267 * boot code is stored.
268 * \param[out] appVerMajor A pointer to a byte where the major version number
269 * of the application code is stored.
270 * \param[out] appVerMinor A pointer to a byte where the minor version number
271 * of the application code is stored.
272 * \param[out] appVerBuild A pointer to a byte where the build number of the application is stored.
273 *
274 * \return \ref j1587OK (zero) if success
275 * \return \ref j1587ERR_xxx (negative) if failure
276 */
277J1587Status J1587LIBAPI j1587GetFirmwareVersion(J1587Handle h,
278 unsigned char *bootVerMajor,
279 unsigned char *bootVerMinor,
280 unsigned char *bootVerBuild,
281 unsigned char *appVerMajor,
282 unsigned char *appVerMinor,
283 unsigned char *appVerBuild);
284
285/**
286 * This function sets the bit rate
287 *
288 * \note The J1587 Interface should not be on bus.
289 *
290 * \param[in] h A handle to an open J1587 channel.
291 * \param[in] bps Bit rate in bits per second.
292 *
293 * \return \ref j1587OK (zero) if success
294 * \return \ref j1587ERR_xxx (negative) if failure
295 */
296J1587Status J1587LIBAPI j1587SetBitrate(J1587Handle h, unsigned int bps);
297
298/**
299 * This function activates the J1587 interface.
300 * \note It will be reset, so any setups done earlier will be lost.
301 *
302 * \param[in] h A handle to an open J1587 channel.
303 *
304 * \return \ref j1587OK (zero) if success
305 * \return \ref j1587ERR_xxx (negative) if failure
306 */
307J1587Status J1587LIBAPI j1587BusOn(J1587Handle h);
308
309/**
310 * This function deactivates the J1587 interface. It will be reset clearing any
311 * settings such as J1587 data buffers active.
312 *
313 * \param[in] h A handle to an open J1587 channel.
314 *
315 * \return \ref j1587OK (zero) if success
316 * \return \ref j1587ERR_xxx (negative) if failure
317 */
318J1587Status J1587LIBAPI j1587BusOff(J1587Handle h);
319
320/**
321 * Return the current timer value (used for timestamps)
322 *
323 * \note For convenience, this call returns the timer value instead of passing
324 * it in a parameter. This means that if the call fails, it will still return
325 * a value (which then is the error code, type casted to a long unsigned
326 * integer - e.g. 0xFFFFFFF2 for \ref j1587ERR_INVHANDLE. Watch out.
327 *
328 * \param[in] h A handle to an open J1587 channel.
329 * \return If the call succeeds, the present timer value is returned.
330 */
331unsigned long J1587LIBAPI j1587ReadTimer(J1587Handle h);
332
333/**
334 * Write a J1587 message. Times out after timeout ms.
335 *
336 * \param[in] h A handle to an open J1587 channel.
337 * \param[in] msg A pointer to a buffer containing the J1587 message.
338 * \param[in] length Length of message, max 0xFFF
339 * \param[in] priority Priority of message, max 0xFF
340 * \param[in] timeout Times out after \a timeout milliseconds
341 *
342 * \return \ref j1587OK (zero) if success
343 * \return \ref j1587ERR_xxx (negative) if failure
344 */
345J1587Status J1587LIBAPI j1587WriteMessageWait(J1587Handle h, const void *msg,
346 unsigned int length,
347 unsigned int priority,
348 DWORD timeout);
349
350/**
351 * Read a J1587 message.
352 *
353 * \param[in] h A handle to an open J1587 channel.
354 * \param[out] msg A pointer to a buffer where the J1587 message will be
355 * stored.
356 * \param[out] msgLength A pointer to an integer where the length of the
357 * received J1587 message will be stored.
358 * \param[out] msgInfo A pointer a \ref J1587MessageInfo structure where the
359 * message information will be stored.
360 * \param[in] timeout Times out after \a timeout milliseconds
361 *
362 * \return \ref j1587OK (zero) if success
363 * \return \ref j1587ERR_NOMSG if nothing is received
364 * \return \ref j1587ERR_xxx (negative) if failure
365 */
366J1587Status J1587LIBAPI j1587ReadMessageWait(J1587Handle h, void *msg,
367 unsigned int *msgLength,
368 J1587MessageInfo *msgInfo,
369 DWORD timeout);
370
371/**
372 * Call this function to make sure all messages transmitted to the
373 * J1587 Interface have been received by it.
374 *
375 * When messages are transmitted to the J1587 Interface, they are queued by
376 * Windows before appearing on the CAN bus.
377 *
378 * \param[in] h A handle to an open J1587 channel.
379 * \param[out] msgInfo A pointer a \ref J1587MessageInfo structure where the
380 * message information will be stored.
381 * \param[in] timeout Times out after \a timeout milliseconds
382 *
383 * \return \ref j1587OK (zero) if all writes are done
384 * \return \ref j1587ERR_xxx (negative) if failure
385 */
386J1587Status J1587LIBAPI j1587WriteSync (J1587Handle h,
387 J1587MessageInfo *msgInfo,
388 DWORD timeout);
389
390/**
391 * With this function, it is possible to change settings on a J1587 Interface
392 * that is on-bus.
393 * When going on-bus, the bitrate and the flag values \ref J1587_REPORT_xxx are set
394 * to the default value (either as hard-coded in the firmware, or as stored in the
395 * non-volatile memory of the J1587 Interface).
396 *
397 * \note The J1587 Interface must be on bus for this command to work.
398 *
399 * \param[in] h A handle to an open J1587 channel.
400 * \param[in] flags Flags, see \ref J1587_REPORT_xxx
401 *
402 * \todo Describe how to use J1587_INTER_CHAR_DELAY_MASK
403 *
404 * \return \ref j1587OK (zero) if all writes are done
405 * \return \ref j1587ERR_xxx (negative) if failure
406 */
407J1587Status J1587LIBAPI j1587Configure(J1587Handle h, unsigned int flags);
408
409
410
411/**
412 * \name Flags for j1587Configure()
413 * \anchor J1587_REPORT_xxx
414 * @{
415 */
416#define J1587_INTER_CHAR_DELAY_MASK 0x0f ///< Inter character delay mask
417#define J1587_REPORT_BAD_CHECKSUM 0x10 ///< Default off
418#define J1587_REPORT_FRAME_DELAY 0x20 ///< Default off
419#define J1587_REPORT_CHAR_DELAY 0x40 ///< Default off
420/** @} */
421
422/**
423 * Return the CAN handle given an open J1587 handle
424 *
425 * \param[in] h A handle to an open J1587 channel.
426 * \param[out] canHandle A pointer to an integer where the CAN handle will be
427 * stored.
428 *
429 * \return \ref j1587OK (zero) if success
430 * \return \ref j1587ERR_xxx (negative) if failure
431 */
432J1587Status J1587LIBAPI j1587GetCanHandle(J1587Handle h, unsigned int *canHandle);
433
434#ifdef __cplusplus
435}
436#endif
437
438/** @} */
439
440#endif // __J1587LIB_H
Note: See TracBrowser for help on using the repository browser.