Kvaser Linux CANLIB

canlib.h File Reference

#include <stdlib.h>
#include "canstat.h"

Data Structures

struct  canNotifyData
struct  canUserIoPortData

Defines

#define CANLIB_DECLARE_ALL
#define WM__CANLIB   648
canOPEN_xxx

These defines are used in canOpenChannel().

#define canWANT_EXCLUSIVE   0x0008
#define canWANT_EXTENDED   0x0010
#define canWANT_VIRTUAL   0x0020
#define canOPEN_EXCLUSIVE   0x0008
#define canOPEN_REQUIRE_EXTENDED   0x0010
#define canOPEN_ACCEPT_VIRTUAL   0x0020
canFILTER_xxx

Flags for canAccept().

#define canFILTER_ACCEPT   1
#define canFILTER_REJECT   2
#define canFILTER_SET_CODE_STD   3
#define canFILTER_SET_MASK_STD   4
#define canFILTER_SET_CODE_EXT   5
#define canFILTER_SET_MASK_EXT   6
#define canFILTER_NULL_MASK   0L
canDRIVER_xxx

CAN driver types - not all are supported on all cards.

#define canDRIVER_NORMAL   4
#define canDRIVER_SILENT   1
#define canDRIVER_SELFRECEPTION   8
#define canDRIVER_OFF   0
canBITRATE_xxx

Common bus speeds. Used in canSetBusParams() and canSetBusParamsC200(). The values are translated in canlib, canTranslateBaud().

Note:
The BAUD_xxx names are only retained for compability.
See also:
Bit Rate Constants
#define canBITRATE_1M   (-1)
#define canBITRATE_500K   (-2)
#define canBITRATE_250K   (-3)
#define canBITRATE_125K   (-4)
#define canBITRATE_100K   (-5)
#define canBITRATE_62K   (-6)
#define canBITRATE_50K   (-7)
#define canBITRATE_83K   (-8)
#define canBITRATE_10K   (-9)
#define BAUD_1M   (-1)
#define BAUD_500K   (-2)
#define BAUD_250K   (-3)
#define BAUD_125K   (-4)
#define BAUD_100K   (-5)
#define BAUD_62K   (-6)
#define BAUD_50K   (-7)
#define BAUD_83K   (-8)
canCHANNELDATA_xxx

These defines are used in canGetChannelData().

#define canCHANNELDATA_CHANNEL_CAP   1
#define canCHANNELDATA_TRANS_CAP   2
#define canCHANNELDATA_CHANNEL_FLAGS   3
#define canCHANNELDATA_CARD_TYPE   4
#define canCHANNELDATA_CARD_NUMBER   5
#define canCHANNELDATA_CHAN_NO_ON_CARD   6
#define canCHANNELDATA_CARD_SERIAL_NO   7
#define canCHANNELDATA_TRANS_SERIAL_NO   8
#define canCHANNELDATA_CARD_FIRMWARE_REV   9
#define canCHANNELDATA_CARD_HARDWARE_REV   10
#define canCHANNELDATA_CARD_UPC_NO   11
#define canCHANNELDATA_TRANS_UPC_NO   12
#define canCHANNELDATA_CHANNEL_NAME   13
#define canCHANNELDATA_DLL_FILE_VERSION   14
#define canCHANNELDATA_DLL_PRODUCT_VERSION   15
#define canCHANNELDATA_DLL_FILETYPE   16
#define canCHANNELDATA_TRANS_TYPE   17
#define canCHANNELDATA_DEVICE_PHYSICAL_POSITION   18
#define canCHANNELDATA_UI_NUMBER   19
#define canCHANNELDATA_TIMESYNC_ENABLED   20
#define canCHANNELDATA_DRIVER_FILE_VERSION   21
#define canCHANNELDATA_DRIVER_PRODUCT_VERSION   22
#define canCHANNELDATA_MFGNAME_UNICODE   23
#define canCHANNELDATA_MFGNAME_ASCII   24
#define canCHANNELDATA_DEVDESCR_UNICODE   25
#define canCHANNELDATA_DEVDESCR_ASCII   26
#define canCHANNELDATA_DRIVER_NAME   27
canCHANNEL_IS_xxx

These channelFlags are used in canGetChannelData() and in conjunction with canCHANNELDATA_CHANNEL_FLAGS.

#define canCHANNEL_IS_EXCLUSIVE   0x0001
#define canCHANNEL_IS_OPEN   0x0002
canHWTYPE_xxx

The following constants can be returned from canGetChannelData(), using the canCHANNELDATA_CARD_TYPE item code. They identify the hardware type for the channel specified in the call to canGetChannelData().

Note:
They indicate a hardware type, but not necessarily a specific product. For example, canHWTYPE_LAPCAN is returned both for LAPcan and LAPcan II. (You can use canGetChannelData() to obtain the UPC/EAN code for the device. This number uniquely identifies the product.)
#define canHWTYPE_NONE   0
#define canHWTYPE_VIRTUAL   1
#define canHWTYPE_LAPCAN   2
#define canHWTYPE_CANPARI   3
#define canHWTYPE_PCCAN   8
#define canHWTYPE_PCICAN   9
#define canHWTYPE_USBCAN   11
#define canHWTYPE_PCICAN_II   40
#define canHWTYPE_USBCAN_II   42
#define canHWTYPE_SIMULATED   44
#define canHWTYPE_ACQUISITOR   46
#define canHWTYPE_LEAF   48
#define canHWTYPE_PC104_PLUS   50
#define canHWTYPE_PCICANX_II   52
#define canHWTYPE_MEMORATOR_II   54
#define canHWTYPE_MEMORATOR_PRO   54
#define canHWTYPE_USBCAN_PRO   56
#define canHWTYPE_IRIS   58
#define canHWTYPE_BLACKBIRD   58
#define canHWTYPE_MEMORATOR_LIGHT   60
#define canHWTYPE_MINIHYDRA   62
#define canHWTYPE_EAGLE   62
#define canHWTYPE_BAGEL   64
#define canHWTYPE_BLACKBIRD_V2   64
#define canHWTYPE_MINIPCIE   66
#define canHWTYPE_USBCAN_KLINE   68
#define canHWTYPE_ETHERCAN   70
#define canHWTYPE_USBCAN_LIGHT   72
canCHANNEL_CAP_xxx

Channel capabilities.

#define canCHANNEL_CAP_EXTENDED_CAN   0x00000001L
#define canCHANNEL_CAP_BUS_STATISTICS   0x00000002L
#define canCHANNEL_CAP_ERROR_COUNTERS   0x00000004L
#define canCHANNEL_CAP_CAN_DIAGNOSTICS   0x00000008L
#define canCHANNEL_CAP_GENERATE_ERROR   0x00000010L
#define canCHANNEL_CAP_GENERATE_OVERLOAD   0x00000020L
#define canCHANNEL_CAP_TXREQUEST   0x00000040L
#define canCHANNEL_CAP_TXACKNOWLEDGE   0x00000080L
#define canCHANNEL_CAP_VIRTUAL   0x00010000L
#define canCHANNEL_CAP_SIMULATED   0x00020000L
#define canCHANNEL_CAP_REMOTE   0x00040000L
canDRIVER_CAP_xxx

Driver (transceiver) capabilities.

#define canDRIVER_CAP_HIGHSPEED   0x00000001L
canIOCTL_xxx

These defines are used in canIoCtl().

#define canIOCTL_PREFER_EXT   1
#define canIOCTL_PREFER_STD   2
#define canIOCTL_CLEAR_ERROR_COUNTERS   5
#define canIOCTL_SET_TIMER_SCALE   6
#define canIOCTL_SET_TXACK   7
#define canIOCTL_GET_RX_BUFFER_LEVEL   8
#define canIOCTL_GET_TX_BUFFER_LEVEL   9
#define canIOCTL_FLUSH_RX_BUFFER   10
#define canIOCTL_FLUSH_TX_BUFFER   11
#define canIOCTL_GET_TIMER_SCALE   12
#define canIOCTL_SET_TXRQ   13
#define canIOCTL_GET_EVENTHANDLE   14
#define canIOCTL_SET_BYPASS_MODE   15
#define canIOCTL_SET_WAKEUP   16
#define canIOCTL_GET_DRIVERHANDLE   17
#define canIOCTL_MAP_RXQUEUE   18
#define canIOCTL_GET_WAKEUP   19
#define canIOCTL_SET_REPORT_ACCESS_ERRORS   20
#define canIOCTL_GET_REPORT_ACCESS_ERRORS   21
#define canIOCTL_CONNECT_TO_VIRTUAL_BUS   22
#define canIOCTL_DISCONNECT_FROM_VIRTUAL_BUS   23
#define canIOCTL_SET_USER_IOPORT   24
#define canIOCTL_GET_USER_IOPORT   25
#define canIOCTL_SET_BUFFER_WRAPAROUND_MODE   26
#define canIOCTL_SET_RX_QUEUE_SIZE   27
#define canIOCTL_SET_USB_THROTTLE   28
#define canIOCTL_GET_USB_THROTTLE   29
#define canIOCTL_SET_BUSON_TIME_AUTO_RESET   30
#define canIOCTL_GET_TXACK   31
#define canIOCTL_SET_LOCAL_TXECHO   32
canOBJBUF_TYPE_xxx
#define canOBJBUF_TYPE_AUTO_RESPONSE   0x01
#define canOBJBUF_TYPE_PERIODIC_TX   0x02
canOBJBUF_AUTO_RESPONSE_xxx

These defines are used in canObjBufSetFlags().

#define canOBJBUF_AUTO_RESPONSE_RTR_ONLY   0x01

Typedefs

typedef unsigned char BYTE
typedef unsigned int DWORD
typedef unsigned int HANDLE
typedef unsigned int BOOL
typedef int canHandle
typedef canHandle CanHandle
typedef struct canNotifyData canNotifyData
typedef canStatus kvStatus

Functions

void canInitializeLibrary (void)
canStatus canClose (const CanHandle hnd)
canStatus canBusOn (const CanHandle hnd)
canStatus canBusOff (const CanHandle hnd)
canStatus canSetBusParams (const CanHandle hnd, long freq, unsigned int tseg1, unsigned int tseg2, unsigned int sjw, unsigned int noSamp, unsigned int syncmode)
canStatus canGetBusParams (const CanHandle hnd, long *freq, unsigned int *tseg1, unsigned int *tseg2, unsigned int *sjw, unsigned int *noSamp, unsigned int *syncmode)
canStatus canSetBusOutputControl (const CanHandle hnd, const unsigned int drivertype)
canStatus canGetBusOutputControl (const CanHandle hnd, unsigned int *drivertype)
canStatus canAccept (const CanHandle hnd, const long envelope, const unsigned int flag)
canStatus canReadStatus (const CanHandle hnd, unsigned long *const flags)
canStatus canReadErrorCounters (const CanHandle hnd, unsigned int *txErr, unsigned int *rxErr, unsigned int *ovErr)
canStatus canWrite (const CanHandle hnd, long id, void *msg, unsigned int dlc, unsigned int flag)
canStatus canWriteSync (const CanHandle hnd, unsigned long timeout)
canStatus canRead (const CanHandle hnd, long *id, void *msg, unsigned int *dlc, unsigned int *flag, unsigned long *time)
canStatus canReadWait (const CanHandle hnd, long *id, void *msg, unsigned int *dlc, unsigned int *flag, unsigned long *time, unsigned long timeout)
canStatus canReadSync (const CanHandle hnd, unsigned long timeout)
canStatus canSetNotify (const CanHandle hnd, void(*callback)(canNotifyData *), unsigned int notifyFlags, void *tag)
canStatus canGetRawHandle (const CanHandle hnd, void *pvFd)
canStatus canTranslateBaud (long *const freq, unsigned int *const tseg1, unsigned int *const tseg2, unsigned int *const sjw, unsigned int *const nosamp, unsigned int *const syncMode)
canStatus canGetErrorText (canStatus err, char *buf, unsigned int bufsiz)
unsigned short canGetVersion (void)
canStatus canIoCtl (const CanHandle hnd, unsigned int func, void *buf, unsigned int buflen)
canStatus canReadTimer (const CanHandle hnd, unsigned long *time)
CanHandle canOpenChannel (int channel, int flags)
canStatus canGetNumberOfChannels (int *channelCount)
canStatus canGetChannelData (int channel, int item, void *buffer, size_t bufsize)
canStatus canSetBusParamsC200 (const CanHandle hnd, BYTE btr0, BYTE btr1)
canStatus canObjBufFreeAll (const CanHandle hnd)
canStatus canObjBufAllocate (const CanHandle hnd, int type)
canStatus canObjBufFree (const CanHandle hnd, int idx)
canStatus canObjBufWrite (const CanHandle hnd, int idx, int id, void *msg, unsigned int dlc, unsigned int flags)
canStatus canObjBufSetFilter (const CanHandle hnd, int idx, unsigned int code, unsigned int mask)
canStatus canObjBufSetFlags (const CanHandle hnd, int idx, unsigned int flags)
canStatus canObjBufSetPeriod (const CanHandle hnd, int idx, unsigned int period)
canStatus canObjBufSetMsgCount (const CanHandle hnd, int idx, unsigned int count)
canStatus canObjBufEnable (const CanHandle hnd, int idx)
canStatus canObjBufDisable (const CanHandle hnd, int idx)
canStatus canObjBufSendBurst (const CanHandle hnd, int idx, unsigned int burstlen)
canStatus canResetBus (const CanHandle hnd)
canStatus canWriteWait (const CanHandle hnd, long id, void *msg, unsigned int dlc, unsigned int flag, unsigned long timeout)
canStatus canFlushReceiveQueue (const CanHandle hnd)
canStatus canFlushTransmitQueue (const CanHandle hnd)

kvCallback_t

kvCallback_t is used by the function kvSetNotifyCallback()The callback function is called with the following arguments:

  • hnd - the handle of the CAN channel where the event happened.
  • context - the context pointer you passed to kvSetNotifyCallback().
  • notifyEvent - one of the canNOTIFY_xxx notification codes.
Note:
It is really the canNOTIFY_xxx codes, and not the canEVENT_xxx codes that the canSetNotify() API is using.
Parameters:
[in]hndAn open handle to a CAN channel.
[in]contextArbitrary user-defined context data which is passed to the callback function.
[in]notifyEventOne or more of the canEVENT_xxx flags.

typedef void(* kvCallback_t )(CanHandle hnd, void *context, unsigned int notifyEvent)
kvStatus kvSetNotifyCallback (const CanHandle hnd, kvCallback_t callback, void *context, unsigned int notifyFlags)

Detailed Description

LICENSE

 This software is dual licensed under the following two licenses:
 BSD-new and GPLv2. You may use either one. See the included
 COPYING file for details.
 License: BSD-new
 ===============================================================================
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:
     * Redistributions of source code must retain the above copyright
       notice, this list of conditions and the following disclaimer.
     * Redistributions in binary form must reproduce the above copyright
       notice, this list of conditions and the following disclaimer in the
       documentation and/or other materials provided with the distribution.
     * Neither the name of the <organization> nor the
       names of its contributors may be used to endorse or promote products
       derived from this software without specific prior written permission.
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT holder>=""> BE LIABLE FOR ANY
 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 License: GPLv2
 ===============================================================================
 This program is free software; you can redistribute it and/or
 modify it under the terms of the GNU General Public License
 as published by the Free Software Foundation; either version 2
 of the License, or (at your option) any later version.
 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.
 You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software
 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 ---------------------------------------------------------------------------
 

DESCRIPTION

Definitions for the CANLIB API.

Author:
Kvaser AB

Define Documentation

#define BAUD_100K   (-5)

The BAUD_xxx names are deprecated, use canBITRATE_100K instead.

#define BAUD_125K   (-4)

The BAUD_xxx names are deprecated, use canBITRATE_125K instead.

#define BAUD_1M   (-1)

The BAUD_xxx names are deprecated, use canBITRATE_1M instead.

Examples:
cancount.c, canmonitor.c, simplewrite.c, and writeloop.c.
#define BAUD_250K   (-3)

The BAUD_xxx names are deprecated, use canBITRATE_250K instead.

#define BAUD_500K   (-2)

The BAUD_xxx names are deprecated, use canBITRATE_500K instead.

Examples:
opentest.c.
#define BAUD_50K   (-7)

The BAUD_xxx names are deprecated, use canBITRATE_50K instead.

#define BAUD_62K   (-6)

The BAUD_xxx names are deprecated, use canBITRATE_62K instead.

#define BAUD_83K   (-8)

The BAUD_xxx names are deprecated, use canBITRATE_83K instead.

#define canBITRATE_100K   (-5)

Used in canSetBusParams() and canSetBusParamsC200(). Indicate a bitrate of 100 kbit/s.

#define canBITRATE_10K   (-9)

Used in canSetBusParams() and canSetBusParamsC200(). Indicate a bitrate of 10 kbit/s.

#define canBITRATE_125K   (-4)

Used in canSetBusParams() and canSetBusParamsC200(). Indicate a bitrate of 125 kbit/s.

#define canBITRATE_1M   (-1)

Used in canSetBusParams() and canSetBusParamsC200(). Indicate a bitrate of 1 Mbit/s.

#define canBITRATE_250K   (-3)

Used in canSetBusParams() and canSetBusParamsC200(). Indicate a bitrate of 250 kbit/s.

#define canBITRATE_500K   (-2)

Used in canSetBusParams() and canSetBusParamsC200(). Indicate a bitrate of 500 kbit/s.

#define canBITRATE_50K   (-7)

Used in canSetBusParams() and canSetBusParamsC200(). Indicate a bitrate of 50 kbit/s.

#define canBITRATE_62K   (-6)

Used in canSetBusParams() and canSetBusParamsC200(). Indicate a bitrate of 62 kbit/s.

#define canBITRATE_83K   (-8)

Used in canSetBusParams() and canSetBusParamsC200(). Indicate a bitrate of 83 kbit/s.

#define canCHANNEL_CAP_BUS_STATISTICS   0x00000002L

Can report busload etc.

#define canCHANNEL_CAP_CAN_DIAGNOSTICS   0x00000008L

Can report CAN diagnostics.

#define canCHANNEL_CAP_ERROR_COUNTERS   0x00000004L

Can return error counters.

#define canCHANNEL_CAP_EXTENDED_CAN   0x00000001L

Can use extended identifiers.

#define canCHANNEL_CAP_GENERATE_ERROR   0x00000010L

Can send error frames.

#define canCHANNEL_CAP_GENERATE_OVERLOAD   0x00000020L

Can send CAN overload frame.

#define canCHANNEL_CAP_REMOTE   0x00040000L

Remote CAN channel (e.g. BlackBird).

#define canCHANNEL_CAP_SIMULATED   0x00020000L

Simulated CAN channel.

#define canCHANNEL_CAP_TXACKNOWLEDGE   0x00000080L

Can report when a CAN messages has been transmitted.

#define canCHANNEL_CAP_TXREQUEST   0x00000040L

Can report when a CAN messsage transmission is initiated.

#define canCHANNEL_CAP_VIRTUAL   0x00010000L

Virtual CAN channel.

#define canCHANNEL_IS_EXCLUSIVE   0x0001

Used with canCHANNELDATA_CHANNEL_FLAGS, indicates that the channel is opened exclusively.

#define canCHANNEL_IS_OPEN   0x0002

Used with canCHANNELDATA_CHANNEL_FLAGS, indicates that the channel is opened.

#define canCHANNELDATA_CARD_FIRMWARE_REV   9

This define is used in canGetChannelData(), buffer mentioned below refers to this functions argument.

buffer points to a 64-bit (8 bytes) area which receives the firmware revision number on the card. This number consists of four 16-bit words: the major revision, the minor revision, the release number and the build number, listed in order from the most significant to the least significant.

Examples:
listChannels.c.
#define canCHANNELDATA_CARD_HARDWARE_REV   10

This define is used in canGetChannelData(), buffer mentioned below refers to this functions argument.

buffer points to a 64-bit (8 bytes) area which receives the hardware revision number on the card. This number consists of four 16-bit words; the two most significant are always 0, and the two least significant are the major revision and the minor revision, listed in order from the most significant to the least significant.

#define canCHANNELDATA_CARD_NUMBER   5

This define is used in canGetChannelData(), buffer mentioned below refers to this functions argument.

buffer points to a 32-bit unsigned integer that receives the card's number in the computer. Each card type is numbered separately. For example, the first LAPcan card in a machine will have number 0, the second LAPcan number 1, etc.

#define canCHANNELDATA_CARD_SERIAL_NO   7

This define is used in canGetChannelData(), buffer mentioned below refers to this functions argument.

buffer points to a 64-bit (8 bytes) area which receives the serial number of the card. If the card doesn't have a serial number, 0 is returned. The serial number is an 8-byte unsigned integer. Currently, no products are using all 8 bytes; at most 4 bytes are used.

Examples:
listChannels.c.
#define canCHANNELDATA_CARD_TYPE   4

This define is used in canGetChannelData(), buffer mentioned below refers to this functions argument.

buffer points to a 32-bit unsigned integer that receives the hardware type of the card. This value is any one of the canHWTYPE_xxx constants.

#define canCHANNELDATA_CARD_UPC_NO   11

This define is used in canGetChannelData(), buffer mentioned below refers to this functions argument.

buffer points to a 8-byte area which receives the UPC (EAN) number for the card. If there is no UPC number, the buffer is filled with zeros. The UPC (EAN) number is coded as a BCD string with the LSB first, so e.g. 733-0130-00122-0 is coded as 0x30001220 0x00073301.

Examples:
listChannels.c.
#define canCHANNELDATA_CHAN_NO_ON_CARD   6

This define is used in canGetChannelData(), buffer mentioned below refers to this functions argument.

buffer points to a 32-bit unsigned integer which receives the channel number on the card.

#define canCHANNELDATA_CHANNEL_CAP   1

This define is used in canGetChannelData(), buffer mentioned below refers to this functions argument.

buffer points to a 32-bit unsigned integer that receives the capabilities of the CAN controller; this is a combination of the canCHANNEL_CAP_xxx flags.

#define canCHANNELDATA_CHANNEL_FLAGS   3

This define is used in canGetChannelData(), buffer mentioned below refers to this functions argument.

Note:
Currently not implemented.
#define canCHANNELDATA_CHANNEL_NAME   13

This define is used in canGetChannelData(), buffer mentioned below refers to this functions argument.

buffer points to an area which receives a zero-terminated string with a clear-text name of the channel.

Note:
Use of this item code is no longer recommended. The returned channel name doesn't contain the exact hardware type (it just contains the device family) and uses zero-based channel numbering, which is not user friendly. Instead, use e.g. canCHANNELDATA_DEVDESCR_ASCII and canCHANNELDATA_CHAN_NO_ON_CARD to build your own channel name.
Examples:
listChannels.c.
#define canCHANNELDATA_DEVDESCR_ASCII   26

This define is used in canGetChannelData(), buffer mentioned below refers to this functions argument.

buffer points to a buffer which receives the product name of the device as a zero-terminated ASCII string.

Examples:
listChannels.c.
#define canCHANNELDATA_DEVDESCR_UNICODE   25

This define is used in canGetChannelData(), buffer mentioned below refers to this functions argument.

buffer points to a buffer which receives the product name of the device as a zero-terminated Unicode string.

#define canCHANNELDATA_DEVICE_PHYSICAL_POSITION   18

This define is used in canGetChannelData(), buffer mentioned below refers to this functions argument.

buffer points to a 32-bit unsigned integer which receives an address indicating where the device is located on its underlying bus. The interpretation of this number is bus-specific. If the address is unknown or the bus driver does not support an address, the bus driver leaves this member at its default value of 0xFFFFFFFF.

The following list describes the information certain bus drivers store in the Address field for their child devices:

  • ISA: Does not supply an address. Defaults to 0xFFFFFFFF.
  • PC Card (PCMCIA): The socket number (typically 0x00 or 0x40)
  • PCI: The device number in the high word and the function number in the low word.
  • USB: The port number.
#define canCHANNELDATA_DLL_FILE_VERSION   14

This define is used in canGetChannelData(), buffer mentioned below refers to this functions argument.

buffer points to an array of 4 16-bit unsigned integers which receives the file version number of the second-level DLL driver file, i.e. the DLL that interfaces between CANLIB32.DLL and the driver proper.

Contents depening on index:

  • 0: 0
  • 1: The build number
  • 2: The minor revision number
  • 3: The major revision number
#define canCHANNELDATA_DLL_FILETYPE   16

This define is used in canGetChannelData(), buffer mentioned below refers to this functions argument.

buffer points to a 32-bit unsigned integer which receives a number that identifies the second-level DLL driver file, i.e. the DLL that interfaces between CANLIB32.DLL and the driver proper.

Values:

  • 1: kvalapw.dll - used with CANLIB up to 2.29.
  • 2: kvalapw2.dll - used with CANLIB from 3.0 and on.
#define canCHANNELDATA_DLL_PRODUCT_VERSION   15

This define is used in canGetChannelData(), buffer mentioned below refers to this functions argument.

buffer points to an array of 4 16-bit unsigned integers which receives the product version number of the second-level DLL driver file, i.e. the DLL that interfaces between CANLIB32.DLL and the driver proper.

Contents depening on index:

  • 0: 0
  • 1: 1
  • 2: The minor revision number
  • 3: The major revision number
#define canCHANNELDATA_DRIVER_FILE_VERSION   21

This define is used in canGetChannelData(), buffer mentioned below refers to this functions argument.

buffer points to an array of four 16-bit unsigned integers which receives the file version number of the kernel-mode driver.

Contents depening on index:

  • 0: The build number
  • 1: 0
  • 2: The minor revision number
  • 3: The major revision number
#define canCHANNELDATA_DRIVER_NAME   27

This define is used in canGetChannelData(), buffer mentioned below refers to this functions argument.

buffer points to a buffer which receives the name of the device driver (e.g. "kcans") as a zero-terminated ASCII string.

Note:
The device driver names have no special meanings and may change from a release to another.
#define canCHANNELDATA_DRIVER_PRODUCT_VERSION   22

This define is used in canGetChannelData(), buffer mentioned below refers to this functions argument.

buffer points to an array of four 16-bit unsigned integers which receives the product version number of the kernel-mode driver.

Contents depening on index:

  • 0: 0
  • 1: 0
  • 2: The minor revision number
  • 3: The major revision number
#define canCHANNELDATA_MFGNAME_ASCII   24

This define is used in canGetChannelData(), buffer mentioned below refers to this functions argument.

buffer points to a buffer which receives the device manufacturer's name as a zero-terminated ASCII string.

#define canCHANNELDATA_MFGNAME_UNICODE   23

This define is used in canGetChannelData(), buffer mentioned below refers to this functions argument.

buffer points to a buffer which receives the device manufacturer's name as a zero-terminated Unicode string.

#define canCHANNELDATA_TIMESYNC_ENABLED   20

This define is used in canGetChannelData(), buffer mentioned below refers to this functions argument.

buffer points to a 32-bit unsigned integer which is set to 0, if the legacy time synchronization is not currently enabled for the specified channel, and 1, if the legacy time synchronization is currently enabled for the specified channel.

Legacy time synchronization is a mechanism that will keep the PC and CAN channel clocks in sync. The synchronization is done in the driver, which periodically calculates the difference between the PC clock and the CAN device clock and compensates for the clock drift by recalculating the CAN message time stamps. You need to enable clock synchronization in the Control Panel using the Kvaser Hardware applet.

Note:
Legacy time synchronization is implemented only on LAPcan and LAPcan II. It is not related to Kvaser MagiSync™ which is implemented in the high-end members of the Kvaser Leaf family. Kvaser MagiSync™ is always enabled and allows for much more accurate time synchronization.
#define canCHANNELDATA_TRANS_CAP   2

This define is used in canGetChannelData(), buffer mentioned below refers to this functions argument.

buffer points to a 32-bit unsigned integer that receives the capabilities of the CAN transceiver; this is a combination of the canDRIVER_CAP_xxx flags.

#define canCHANNELDATA_TRANS_SERIAL_NO   8

This define is used in canGetChannelData(), buffer mentioned below refers to this functions argument.

buffer points to a 64-bit (8 bytes) area which receives the serial number of the transceiver. The serial number is an 8-byte unsigned integer. If the transceiver doesn't have a serial number, 0 is returned.

#define canCHANNELDATA_TRANS_TYPE   17

This define is used in canGetChannelData(), buffer mentioned below refers to this functions argument.

buffer points to a 32-bit unsigned integer which receives the CAN transceiver type of the specified channel. This value is one of the canTRANSCEIVER_TYPE_xxx

#define canCHANNELDATA_TRANS_UPC_NO   12

This define is used in canGetChannelData(), buffer mentioned below refers to this functions argument.

buffer points to a 8-byte area which receives the UPC (EAN) number for the transceiver. If there is no UPC number, the buffer is filled with zeros. The UPC (EAN) number is coded as a BCD string with the LSB first, so e.g. 733-0130-00122-0 is coded as 0x30001220 0x00073301.

#define canCHANNELDATA_UI_NUMBER   19

This define is used in canGetChannelData(), buffer mentioned below refers to this functions argument.

buffer points to a 32-bit unsigned integer which receives a number associated with the device that can be displayed in the user interface. This number is typically a user-perceived slot number, such as a number printed next to the slot on the board, or some other number that makes locating the physical device easier for the user. For buses with no such convention, or when the UI number is unknown, 0xFFFFFFFF is returned.

#define canDRIVER_CAP_HIGHSPEED   0x00000001L
#define canDRIVER_NORMAL   4

The "normal" driver type (push-pull). This is the default.

Examples:
canmonitor.c, simplewrite.c, and writeloop.c.
#define canDRIVER_OFF   0

The driver is turned off. Not implemented in all types of hardware.

#define canDRIVER_SELFRECEPTION   8

Self-reception. Not implemented.

#define canDRIVER_SILENT   1

Sets the CAN controller in Silent Mode; that is, it doesn't send anything, not even ACK bits, on the bus. Reception works as usual.

Note:
The values 2,3,5,6,7 are reserved values for compatibility reasons.
#define canFILTER_ACCEPT   1

Sets the code for standard (11-bit) identifiers.

#define canFILTER_NULL_MASK   0L

Sets the code for standard (11-bit) identifiers.

#define canFILTER_REJECT   2

Sets the code for standard (11-bit) identifiers.

#define canFILTER_SET_CODE_EXT   5

Sets the code for extended (29-bit) identifiers.

#define canFILTER_SET_CODE_STD   3

Sets the code for standard (11-bit) identifiers.

#define canFILTER_SET_MASK_EXT   6

Sets the mask for extended (29-bit) identifiers.

#define canFILTER_SET_MASK_STD   4

Sets the mask for standard (11-bit) identifiers.

#define canHWTYPE_ACQUISITOR   46

Kvaser Acquisitor (obsolete).

#define canHWTYPE_BAGEL   64

Obsolete name, use canHWTYPE_BLACKBIRD_V2 instead.

#define canHWTYPE_BLACKBIRD   58

Kvaser BlackBird.

#define canHWTYPE_BLACKBIRD_V2   64

Kvaser BlackBird v2.

#define canHWTYPE_CANPARI   3

CANpari (obsolete).

#define canHWTYPE_EAGLE   62

Kvaser Eagle family.

#define canHWTYPE_ETHERCAN   70

Kvaser Ethercan.

#define canHWTYPE_IRIS   58

Iris.

#define canHWTYPE_LAPCAN   2

LAPcan Family.

#define canHWTYPE_LEAF   48

Kvaser Leaf Family.

#define canHWTYPE_MEMORATOR_II   54

Kvaser Memorator Professional family.

#define canHWTYPE_MEMORATOR_LIGHT   60

Kvaser Memorator Light.

#define canHWTYPE_MEMORATOR_PRO   54

Kvaser Memorator Professional family.

#define canHWTYPE_MINIHYDRA   62

Eagle née Minihydra.

#define canHWTYPE_MINIPCIE   66

Kvaser Mini PCI Express.

#define canHWTYPE_NONE   0

Unknown or undefined.

#define canHWTYPE_PC104_PLUS   50

Kvaser PC104+.

#define canHWTYPE_PCCAN   8

PCcan Family.

#define canHWTYPE_PCICAN   9

PCIcan Family.

#define canHWTYPE_PCICAN_II   40

PCIcan II family.

#define canHWTYPE_PCICANX_II   52

Kvaser PCIcanx II.

#define canHWTYPE_SIMULATED   44

Simulated CAN bus for Kvaser Creator (obsolete).

#define canHWTYPE_USBCAN   11

USBcan (obsolete).

#define canHWTYPE_USBCAN_II   42

USBcan II, USBcan Rugged, Kvaser Memorator.

#define canHWTYPE_USBCAN_KLINE   68

USBcan Pro HS/K-Line.

#define canHWTYPE_USBCAN_LIGHT   72

Kvaser USBcan Light.

#define canHWTYPE_USBCAN_PRO   56

Kvaser USBcan Professional.

#define canHWTYPE_VIRTUAL   1

The virtual CAN bus.

#define canIOCTL_CLEAR_ERROR_COUNTERS   5

This define is used in canIoCtl(), buf and buflen refers to this functions arguments.

Tells CANLIB to clear the CAN error counters. The contents of buf and buflen are ignored.

Note:
Not all CAN controllers support this operation (and if they don't, nothing will happen.)
#define canIOCTL_CONNECT_TO_VIRTUAL_BUS   22

This define is used in canIoCtl(), buf mentioned below refers to this functions argument.

Connects the handle to the virtual bus number (0..31) which the buf points to.

#define canIOCTL_DISCONNECT_FROM_VIRTUAL_BUS   23

This define is used in canIoCtl(), buf mentioned below refers to this functions argument.

Disonnects the handle from the virtual bus number (0..31) which the buf points to.

#define canIOCTL_FLUSH_RX_BUFFER   10

This define is used in canIoCtl(), buf and buflen refers to this functions arguments.

Discard the current contents of the RX queue. The values of buf and buflen are ignored.

Note:
This is the same thing as calling canFlushReceiveQueue()
#define canIOCTL_FLUSH_TX_BUFFER   11

This define is used in canIoCtl(), buf and buflen refers to this functions arguments.

Discard the current contents of the TX queue. The values of buf and buflen are ignored.

Note:
This is the same thing as calling canFlushTransmitQueue().
#define canIOCTL_GET_DRIVERHANDLE   17

This define is used in canIoCtl(), buf mentioned below refers to this functions argument.

buf points to a HANDLE which receives the Windows handle related to the CANLIB handle.

#define canIOCTL_GET_EVENTHANDLE   14

This define is used in canIoCtl(), buf mentioned below refers to this functions argument.

buf points at a DWORD which receives a Windows Event handle which can be passed to the Win32 API WaitForSingleObject. The event is signaled when "something" (typically that a CAN message has been received or transmitted) happens in the driver.

Note:
There is no more information available as to what happened when this call returns. The call may return on an "internal" event in CANLIB and your application must be prepared to handle this (i.e. go to sleep again.)
If canWaitForEvent() returns with success status (canOK), you must call canRead() repeatedly until it returns canERR_NOMSG, before calling canWaitForEvent() again. This will flush the driver's internal event queues. Failure to call canRead() can cause canWaitForEvent() to get stuck in a state where it always sleeps for the specified timeout and then returns with canERR_TIMEOUT.
See also:
canWaitForEvent()
Note:
You must not set, reset, nor close this handle. Waiting on it is the only supported operation.
#define canIOCTL_GET_REPORT_ACCESS_ERRORS   21

This define is used in canIoCtl(), buf mentioned below refers to this functions argument.

buf points to a BYTE which receives the current setting of the access error reporting (0 or 1.)

#define canIOCTL_GET_RX_BUFFER_LEVEL   8

This define is used in canIoCtl(), buf mentioned below refers to this functions argument.

buf points at a DWORD which receives the current RX queue level. The returned value is approximative (this is because not all hardware supports retrieving the queue levels. In that case a best-effort guess is returned. Also note that a device with embedded CPU will report its queue levels to the host computer after a short delay that depends on the bus traffic intensity, and consequently the value returned by the call to canIoCtl() might be a few milliseconds old.)

#define canIOCTL_GET_TIMER_SCALE   12

This define is used in canIoCtl(), buf mentioned below refers to this functions argument.

buf points to a DWORD which contains the desired time-stamp clock resolution in microseconds. Note that the accuracy of the clock isn't affected. The default value is 1000 microseconds, i.e. one millisecond.

#define canIOCTL_GET_TX_BUFFER_LEVEL   9

This define is used in canIoCtl(), buf mentioned below refers to this functions argument.

buf points at a DWORD which receives the current TX queue level. The returned value is approximative (this is because not all hardware supports retrieving the queue levels. In that case a best-effort guess is returned. Also note that a device with embedded CPU will report its queue levels to the host computer after a short delay that depends on the bus traffic intensity, and consequently the value returned by the call to canIoCtl() might be a few milliseconds old.)

#define canIOCTL_GET_TXACK   31

This define is used in canIoCtl(), buf mentioned below refers to this functions argument.

Returns the state of the Transmit Acknowledge as a DWORD in buf:

  • 0: Transmit Acknowledges is turned off.
  • 1: Transmit Acknowledges is turned on.
  • 2: Transmit Acknowledges is turned off, even for the driver's internal usage.
#define canIOCTL_GET_USB_THROTTLE   29

This define is used in canIoCtl().

This is only intended for internal use.

#define canIOCTL_GET_USER_IOPORT   25

This define is used in canIoCtl(), buf mentioned below refers to this functions argument.

buf points to a canUserIoPortData struct that contains a port number. After the call, the struct will contain the current value of the I/O port. This is used by special hardware only.

#define canIOCTL_GET_WAKEUP   19

This define is used in canIoCtl().

This is only intended for internal use.

#define canIOCTL_MAP_RXQUEUE   18

This define is used in canIoCtl().

This is only intended for internal use.

#define canIOCTL_PREFER_EXT   1

This define is used in canIoCtl(), buf and buflen refers to this functions arguments.

Tells CANLIB to "prefer" extended identifiers; that is, if you send a message with canWrite() and don't specify canMSG_EXT nor canMSG_STD, canMSG_EXT will be assumed. The contents of buf and buflen are ignored. canRead() et al will set canMSG_EXT and/or canMSG_STD as usual and are not affected by this call.

#define canIOCTL_PREFER_STD   2

This define is used in canIoCtl(), buf and buflen refers to this functions arguments.

Tells CANLIB to "prefer" standard identifiers; that is, if you send a message with canWrite() and don't specify canMSG_EXT nor canMSG_STD, canMSG_STD will be assumed. The contents of buf and buflen are ignored. canRead() et al will set canMSG_EXT and/or canMSG_STD as usual and are not affected by this call.

#define canIOCTL_SET_BUFFER_WRAPAROUND_MODE   26

This define is used in canIoCtl().

This is only intended for internal use.

#define canIOCTL_SET_BUSON_TIME_AUTO_RESET   30

This define is used in canIoCtl(), buf mentioned below refers to this functions argument.

buf points to a DWORD. If the value is zero, the CAN clock will not be reset at buson for the handle. Otherwise, the CAN clock will be reset at buson.

Default value is 1, the CAN clock will be reset at buson.

#define canIOCTL_SET_BYPASS_MODE   15

This define is used in canIoCtl(), buf mentioned below refers to this functions argument.

Note:
Not yet implemented.
#define canIOCTL_SET_LOCAL_TXECHO   32

This define is used in canIoCtl(), buf mentioned below refers to this functions argument.

buf points to an unsigned byte. If the value is zero, the local transmit echo is turned off for the handle. Otherwise, local transmit echo is turned on.

Local transmit echo is turned on by default on all handles. This means that if two handles are open on the same channel, and a message is transmitted on the first handle, it will be received as a normal message on the second handle. Use the canIOCTL_SET_LOCAL_TXECHO function code to turn this function off, if it is not desired on a certain handle.

#define canIOCTL_SET_REPORT_ACCESS_ERRORS   20

This define is used in canIoCtl(), buf mentioned below refers to this functions argument.

buf points to a BYTE which contains

  • 0 to turn access error reporting off, and
  • 1 to turn access error reporting on.

Default value is 0, access error reporting off.

#define canIOCTL_SET_RX_QUEUE_SIZE   27

This define is used in canIoCtl(), buf mentioned below refers to this functions argument.

Use this function code to set the size of the receive buffer for a specific handle. buf points to an unsigned integer which contains the new size (number of messages) of the receive buffer.

Note:
The receive buffer consumes system nonpaged pool memory, which is a limited resource. Do not increase the receive buffer size unless you have good reasons to do so.
You can't use this function code when the channel is on bus.
#define canIOCTL_SET_TIMER_SCALE   6

This define is used in canIoCtl(), buf mentioned below refers to this functions argument.

buf points to a DWORD which contains the desired time-stamp clock resolution in microseconds. The default value is 1000 microseconds, i.e. one millisecond.

Note:
The accuracy of the clock isn't affected.
#define canIOCTL_SET_TXACK   7

This define is used in canIoCtl(), buf mentioned below refers to this functions argument.

buf points to a DWORD which contains

  • 0: to turn Transmit Acknowledges off.
  • 1: to turn Transmit Acknowledges on.
  • 2: to turn Transmit Acknowledges off, even for the driver's internal usage. This might enhance performance but will cause some other APIs to stop working (for example, the current size of the transmit queue can not be read when this mode is active.)

The default value is 0, Transmit Acknowledge is off.

#define canIOCTL_SET_TXRQ   13

This define is used in canIoCtl(), buf mentioned below refers to this functions argument.

buf points to a DWORD which contains

  • 0 to turn Transmit Requests off.
  • 1 to turn Transmit Requests on.

Default value is 0, Transmit Requests off.

#define canIOCTL_SET_USB_THROTTLE   28

This define is used in canIoCtl().

This is only intended for internal use.

#define canIOCTL_SET_USER_IOPORT   24

This define is used in canIoCtl(), buf mentioned below refers to this functions argument.

buf points to a canUserIoPortData struct that contains a port number and a port value to set. This is used by special hardware only.

#define canIOCTL_SET_WAKEUP   16

This define is used in canIoCtl().

This is only intended for internal use.

#define CANLIB_DECLARE_ALL
#define canOBJBUF_AUTO_RESPONSE_RTR_ONLY   0x01

This define is used in canObjBufSetFlags().

For auto-response buffers only. When this flag is in effect, the buffer will auto-respond to remote requests only. If this flag is not in effect, the buffer will auto-respond to both remote requests and ordinary data frames.

#define canOBJBUF_TYPE_AUTO_RESPONSE   0x01

The buffer is an auto-response buffer.

#define canOBJBUF_TYPE_PERIODIC_TX   0x02

The buffer is an auto-transmit buffer.

#define canOPEN_ACCEPT_VIRTUAL   0x0020

Allow opening of virtual channels as well as physical channels.

This define is used in canOpenChannel().

See also:
Virtual Channels
#define canOPEN_EXCLUSIVE   0x0008

Don't allow sharing of this circuit between applications.

This define is used in canOpenChannel()

Examples:
busparms.c, cancount.c, canmonitor.c, simplewrite.c, and writeloop.c.
#define canOPEN_REQUIRE_EXTENDED   0x0010

This flag causes two things to happen:

  • The call will fail if the specified circuit doesn't allow extended CAN (CAN 2.0B).
  • If no frame-type flag is specified in a call to canWrite, it is assumed that extended CAN should be used.

This define is used in canOpenChannel().

Examples:
busparms.c, cancount.c, canmonitor.c, simplewrite.c, and writeloop.c.
#define canWANT_EXCLUSIVE   0x0008

Don't allow sharing of this circuit between applications.

This define is used in canOpenChannel()

Examples:
opentest.c.
#define canWANT_EXTENDED   0x0010

Don't allow sharing of this circuit between applications.

This define is used in canOpenChannel()

Examples:
opentest.c.
#define canWANT_VIRTUAL   0x0020

Don't allow sharing of this circuit between applications.

This define is used in canOpenChannel()

#define WM__CANLIB   648

Notify message sent to the application window


Typedef Documentation

typedef unsigned int BOOL
typedef unsigned char BYTE
typedef int canHandle

Handle to an opened circuit.

Handle to an opened circuit.

typedef unsigned int DWORD
typedef unsigned int HANDLE
typedef void( * kvCallback_t)(CanHandle hnd, void *context, unsigned int notifyEvent)

The kvSetNotifyCallback() function registers a callback function which is called when certain events occur.

You can register at most one callback function per handle at any time.

To remove the callback, call kvSetNotifyCallback() with a NULL pointer in the callback argument.

Note:
The callback function is called in the context of a high-priority thread created by CANLIB. You should take precaution not to do any time consuming tasks in the callback. You must also arrange the synchronization between the callback and your other threads yourself.
Parameters:
[in]hndAn open handle to a CAN channel.
[in]callbackA pointer to a callback function of type kvCallback_t
[in]contextA pointer to arbitrary user-defined context data which is passed to the callback function.
[in]notifyFlagsOne or more of the canNOTIFY_xxx flags.
Returns:
canOK (zero) if success
canERR_xxx (negative) if failure
See also:
canSetNotify()

Contains status codes according to canSTAT_xxx.