Kvaser CANLIB

General

Functions

void canInitializeLibrary (void)
canStatus canGetErrorText (canStatus err, char *buf, unsigned int bufsiz)
unsigned short canGetVersion (void)
canStatus canIoCtl (const int hnd, unsigned int func, void *buf, unsigned int buflen)
canStatus canGetNumberOfChannels (int *channelCount)
canStatus canGetChannelData (int channel, int item, void *buffer, size_t bufsize)
BOOL canProbeVersion (const int hnd, int major, int minor, int oem_id, unsigned int flags)
canStatus canUnloadLibrary (void)
canStatus kvGetApplicationMapping (int busType, char *appName, int appChannel, int *resultingChannel)
canStatus kvBeep (const int hnd, int freq, unsigned int duration)
canStatus kvSelfTest (const int hnd, unsigned long *presults)
canStatus kvFlashLeds (const int hnd, int action, int timeout)
canStatus kvAnnounceIdentity (const int hnd, void *buf, size_t bufsiz)
canStatus kvAnnounceIdentityEx (const int hnd, int type, void *buf, size_t bufsiz)
kvStatus kvGetSupportedInterfaceInfo (int index, char *hwName, size_t nameLen, int *hwType, int *hwBusType)
kvStatus kvReadTimer (const int hnd, unsigned int *time)
kvStatus kvReadTimer64 (const int hnd, 1 *time)
kvStatus kvReadDeviceCustomerData (const int hnd, int userNumber, int itemNumber, void *data, size_t bufsiz)
kvStatus kvDeviceSetMode (const int hnd, int mode)
kvStatus kvDeviceGetMode (const int hnd, int *result)
kvStatus kvPingRequest (const int hnd, unsigned int *requestTime)
kvStatus kvPingGetLatest (const int hnd, unsigned int *requestTime, unsigned int *pingTime)

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.

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

Function Documentation

canStatus canGetChannelData ( int  channel,
int  item,
void *  buffer,
size_t  bufsize 
)
C#
static Canlib.canStatus canGetChannelData(int channel, int item, out object buffer);
Delphi
function canGetChannelData(channel, item: Integer; var buffer; bufsize: Cardinal): canStatus;

This function can be used to retrieve certain pieces of information about a channel.

Note:
You must pass a channel number and not a channel handle.
Parameters:
[in]channelThe number of the channel you are interested in. Channel numbers are integers in the interval beginning at 0 (zero) and ending at the value returned by canGetNumberOfChannels() minus 1.
[in]itemThis parameter specifies what data to obtain for the specified channel. The value is one of the constants canCHANNELDATA_xxx.
[out]bufferThe address of a buffer which is to receive the data.
[in]bufsizeThe size of the buffer to which the buffer parameter points.
Returns:
canOK (zero) if success
canERR_xxx (negative) if failure
See also:
Code Examples
canGetNumberOfChannels()
Examples:
candemo.cpp, channeldata.c, JoyStick.cpp, and kvTimeStampTester.c.
canStatus canGetErrorText ( canStatus  err,
char *  buf,
unsigned int  bufsiz 
)
C#
static Canlib.canStatus canGetErrorText(Canlib.canStatus err, out string buf_str);
Delphi
function canGetErrorText(err: canStatus; buf: PChar; bufsiz: Cardinal): canStatus;

This function translates an error code (canERR_xxx) to a human-readable, English text.

Parameters:
[in]errThe error code.
[out]bufThe buffer which is to receive the text, which is a zero-terminated string (provided the buffer is large enough.)
[in]bufsizThe length of the input buffer.
Returns:
canOK (zero) if success
canERR_xxx (negative) if failure
See also:
Code Examples
Examples:
candemo.cpp, candump.c, canecho.c, channeldata.c, CLRcandump.cpp, gensig.c, JoyStick.cpp, kvTimeStampTester.c, swc.c, thread.c, and tx.c.
canStatus canGetNumberOfChannels ( int *  channelCount)
C#
static Canlib.canStatus canGetNumberOfChannels(out int channelCount);
Delphi
function canGetNumberOfChannels(var channelCount: Integer): canStatus;

This function returns the number of available CAN channels in the computer. The virtual channels are included in this number.

Parameters:
[out]channelCountA pointer to a DWORD which will receive the current number of channels.
Returns:
canOK (zero) if success
canERR_xxx (negative) if failure
See also:
Code Examples, Virtual Channels
canGetChannelData()
Examples:
candemo.cpp, and channeldata.c.
unsigned short canGetVersion ( void  )
C#
static short canGetVersion();
Delphi
function canGetVersion: Word;

This API call returns the version of the CANLIB API DLL (canlib32.dll). The most significant byte is the major version number and the least significant byte is the minor version number.

The actual version of the different driver files can be obtained by studying the version resources in each of the files.

Note:
The version number of the canlib32.dll file is not related to the product version of CANLIB you are using. CANLIB consists of several driver and DLL files. To obtain the product version, use canGetVersionEx().
Returns:
version number of canlib32.dll
See also:
Version Checking
canGetVersionEx(), canProbeVersion()
void canInitializeLibrary ( void  )
C#
static void canInitializeLibrary(void);
Delphi
procedure canInitializeLibrary;

This function must be called before any other functions is used. It will initialize the driver.

You may call canInitializeLibrary() more than once. The actual initialization will take place only once.

Any errors encountered during library initialization will be "silent" and an appropriate canERR_xxx error code will be returned later on when canOpenChannel() (or any other API call that requires initialization) is called.

See also:
Code Examples
Examples:
candemo.cpp, candump.c, canecho.c, channeldata.c, CLRcandump.cpp, envvar.c, gensig.c, JoyStick.cpp, kvTimeStampTester.c, read_customer_data.c, swc.c, thread.c, and tx.c.
canStatus canIoCtl ( const int  hnd,
unsigned int  func,
void *  buf,
unsigned int  buflen 
)
C#
static Canlib.canStatus canIoCtl(int handle, int func, int val);
static Canlib.canStatus canIoCtl(int handle, int func, out int val);
static Canlib.canStatus canIoCtl(int handle, int func, out string str_buf);
static Canlib.canStatus canIoCtl(int handle, int func, ref object obj_buf);
Delphi
function canIoCtl(handle: canHandle; func: Cardinal; buf: Pointer; buflen: Cardinal): canStatus;

This API call performs several different functions; these are described below. The functions are handle-specific unless otherwise noted; this means that they affect only the handle you pass to canIoCtl(), whereas other open handles will remain unaffected. The contents of buf after the call is dependent on the function code you specified.

Parameters:
[in]hndA handle to an open circuit.
[in]funcA canIOCTL_xxx function code
[in,out]bufPointer to a buffer containing function-dependent data; or a NULL pointer for certain function codes. The buffer can be used for both input and output depending on the function code. See canIOCTL_xxx.
[in]buflenThe length of the buffer.
Returns:
canOK (zero) if success
canERR_xxx (negative) if failure
Examples:
candemo.cpp, gensig.c, and kvTimeStampTester.c.
BOOL canProbeVersion ( const int  hnd,
int  major,
int  minor,
int  oem_id,
unsigned int  flags 
)
C#
static bool canProbeVersion(int hnd, int major, int minor, int oem_id, int flags);
Delphi
function canProbeVersion(handle: canHandle; major, minor, oem_id: Integer; flags: Cardinal): Boolean;

This function checks whether a specific version of CANLIB is installed on the system.

The default behaviour of canProbeVersion is to accept

  • the version specified by major and minor, and
  • any later version, and
  • all beta versions.

You get the default behaviour by setting flags to 0. Use any combination of the canVERSION_xxx flags to modify the behaviour.

Note:
Different handles might have different driver versions installed. This should not normally be the case but it might happen anyway. You should check the version for each handle you open, e.g. directly after calling canOpenChannel().
Parameters:
[in]hndA handle to an open circuit.
[in]majorThe major version number of the version to test for.
[in]minorThe minor version number of the version to test for.
[in]oem_idReserved, must be zero.
[in]flagsAny combination of the canVERSION_xxx flags, or 0.
Returns:
TRUE if the specified version of CANLIB is installed on the system.
See also:
Version Checking
Code Examples
canGetVersion(), canGetVersionEx(), canGetChannelData()
canStatus canUnloadLibrary ( void  )
C#
static Canlib.canStatus canUnloadLibrary();
Delphi
function canUnloadLibrary: Integer;

Use this function if you are loading CANLIB32.DLL dynamically (that is, using the Win32 API LoadLibrary) and need to unload it using the Win32 API FreeLibrary. canUnloadLibrary() will free allocated memory, unload the DLLs canlib32.dll has loaded and de-initialize data structures. You must call canInitializeLibrary() again to use the API functions in canlib32.dll.

Returns:
canOK (zero) if success
canERR_xxx (negative) if failure
See also:
canInitializeLibrary()
canStatus kvAnnounceIdentity ( const int  hnd,
void *  buf,
size_t  bufsiz 
)
C#
static Canlib.canStatus kvAnnounceIdentity(int hnd, object buffer);
Delphi
function kvAnnounceIdentity(handle: canHandle; var buf; bufsiz: Cardinal): canStatus;

The kvAnnounceIdentity function is used by certain OEM applications.

Parameters:
[in]hndAn open handle to a CAN channel.
[out]bufA pointer to the data to be sent to the driver.
[in]bufsizThe size, in bytes, of the buffer that buf points to.
Returns:
canOK (zero) if success
canERR_xxx (negative) if failure
canStatus kvAnnounceIdentityEx ( const int  hnd,
int  type,
void *  buf,
size_t  bufsiz 
)

The kvAnnounceIdentityEx function is used by certain OEM applications.

Parameters:
[in]hndAn open handle to a CAN channel.
[in]typeType of announcement.
[out]bufA pointer to the data to be sent to the driver.
[in]bufsizThe size, in bytes, of the buffer that buf points to.
Returns:
canOK (zero) if success
canERR_xxx (negative) if failure
canStatus kvBeep ( const int  hnd,
int  freq,
unsigned int  duration 
)
C#
static Canlib.canStatus kvBeep(int hnd, int freq, int duration);
Delphi
function kvBeep(handle: canHandle; freq: Integer; duration: Cardinal): canStatus;

The kvBeep function emits a sound of a specific frequency and duration from the loudspeaker on the device.

Note:
This function requires that a loudspeaker be present on the hardware.
Parameters:
[in]hndAn open handle to a CAN channel.
[in]freqThe frequency (in Hertz) of the sound.
[in]durationThe duration of the sound, in milliseconds.
Returns:
canOK (zero) if success
canERR_xxx (negative) if failure
kvStatus kvDeviceGetMode ( const int  hnd,
int *  result 
)
C#
static Canlib.canStatus kvDeviceGetMode(int hnd, out int result);
Delphi
function kvDeviceGetMode(hnd: canHandle; var mode: Integer): kvStatus;

The kvDeviceGetMode() reads the current device's specific mode.

Note:
The mode is device specific, which means that not all modes are implemented in all products.
Parameters:
[in]hndAn open handle to a CAN channel.
[out]resultA pointer to a 32-bit integer that will receive the kvDEVICE_MODE_xxx value.
Returns:
canOK (zero) if success
canERR_xxx (negative) if failure
See also:
kvDeviceSetMode()
kvStatus kvDeviceSetMode ( const int  hnd,
int  mode 
)
C#
static Canlib.canStatus kvDeviceSetMode(int hnd, int mode);
Delphi
function kvDeviceSetMode(hnd: canHandle; mode: Integer): kvStatus;

The kvDeviceSetMode() sets the mode.

Note:
The mode is device specific, which means that not all modes are implemented in all products.
Parameters:
[in]hndAn open handle to a CAN channel.
[in]modeOne of the kvDEVICE_MODE_xxx constants, defining which mode to use.
Returns:
canOK (zero) if success
canERR_xxx (negative) if failure
See also:
kvDeviceGetMode()
canStatus kvFlashLeds ( const int  hnd,
int  action,
int  timeout 
)
C#
static Canlib.canStatus kvFlashLeds(int hnd, int action, int timeout);
Delphi
function kvFlashLeds(handle: canHandle; action: Integer; timeout: Integer): canStatus;

The kvFlashLeds function will turn the LEDs on the device on or off.

Parameters:
[in]hnd
[in]actionOne of the kvLED_ACTION_xxx constants, defining which LED to turn on or off.
[in]timeoutSpecifies the time, in milliseconds, during which the action is to be carried out. When the timeout expires, the LED(s) will return to its ordinary function.
Returns:
canOK (zero) if success
canERR_xxx (negative) if failure
canStatus kvGetApplicationMapping ( int  busType,
char *  appName,
int  appChannel,
int *  resultingChannel 
)
C#
static Canlib.canStatus kvGetApplicationMapping(int busType, string appName, int appChannel, out int resultingChannel);
Delphi
function kvGetApplicationMapping(busType: Integer; appName: PChar; appChannel: Integer; var resultingChannel: Integer): canStatus;
Note:
The kvGetApplicationMapping function is presently not implemented.
Parameters:
busType
appName
appChannel
resultingChannel
Returns:
canOK (zero) if success
canERR_xxx (negative) if failure
kvStatus kvGetSupportedInterfaceInfo ( int  index,
char *  hwName,
size_t  nameLen,
int *  hwType,
int *  hwBusType 
)
C#
static Canlib.canStatus kvGetSupportedInterfaceInfo(int index, out string hwName, out int hwType, out int hwBusType);
Delphi
function kvGetSupportedInterfaceInfo(index: Integer; hwName: PChar; nameLen: Cardinal; var hwType: Integer; var hwBusType: Integer): kvStatus;

The kvGetSupportedInterfaceInfo function returns information about the different supported hardware types in the installed version of CANLIB.

This function is used to enumerate all the supported hardware types in the installed version of CANLIB. It does not return a complete list of all supported devices, nor does it return a list of the presently installed hardware. The returned data indicates which device families are supported.

For example, a returned set of data might be:

This means that

  • the presently installed version of CANLIB supports members in the Kvaser Memorator Pro family (e.g. the HS/HS and the HS/LS),
  • the members of the Kvaser Memorator Pro family are USB devices,
  • the members of the Kvaser Memorator Pro family use the canHWTYPE_MEMORATOR_PRO hardware type.

The kvGetSupportedInterfaceInfo() function is intended to help application designers build a bus-oriented display of the different installed and/or supported Kvaser devices in the computer.

Parameters:
[in]indexUse this parameter to enumerate the different supported hardware types. Start with index = 0, and then call kvGetSupportedInterfaceInfo again() with index = 1,2,3,... until the function returns an error code.
[out]hwNameA pointer to a buffer that will receive the name of the hardware family, as a zero-terminated ASCII string.
[in]nameLenThe length of the hwName buffer.
[out]hwTypePointer to a 32-bit integer that will receive the hardware type (one of the canHWTYPE_xxx constants.)
[out]hwBusTypePointer to a 32-bit integer that will receive the bus type (one of the kvBUSTYPE_xxx constants.)
Returns:
canOK (zero) if success
canERR_xxx (negative) if failure
See also:
canBusOn(), canResetBus()
kvStatus kvPingGetLatest ( const int  hnd,
unsigned int *  requestTime,
unsigned int *  pingTime 
)
C#
static Canlib.canStatus kvPingGetLatest(int hnd, out uint requestTime, out uint pingTime);
Delphi
function kvPingGetLatest(hnd: canHandle; var requestTime: Cardinal; var pingTime: Cardinal): kvStatus;

This retrieves the latest ping time issued by an earlier call to kvPingRequest()

Parameters:
[in]hndA handle to an open circuit.
[out]requestTimeTime of request in microseconds. Used for matching answer to request.
[out]pingTimeLatest value of ping time in milliseconds.
Returns:
canOK (zero) if success
canERR_xxx (negative) if failure
kvStatus kvPingRequest ( const int  hnd,
unsigned int *  requestTime 
)
C#
static Canlib.canStatus kvPingRequest(int hnd, out uint requestTime);
Delphi
function kvPingRequest(hnd: canHandle; var requestTime: Cardinal): kvStatus;

This function sends an active ping to a device. The ping time can later be retrieved using kvPingGetLatest().

Parameters:
[in]hndA handle to an open circuit.
[out]requestTimeTime of request in microseconds. Used for matching answer to request.
Returns:
canOK (zero) if success
canERR_xxx (negative) if failure
kvStatus kvReadDeviceCustomerData ( const int  hnd,
int  userNumber,
int  itemNumber,
void *  data,
size_t  bufsiz 
)
C#
static Canlib.canStatus kvReadDeviceCustomerData(int hnd, int userNumber, int itemNumber, byte[] data, int bufsize);
Delphi
function kvReadDeviceCustomerData(hnd: canHandle;userNumber, itemNumber: Integer; var data; bufsize: Cardinal): kvStatus;

Reading customer data works with Kvaser Leaf (of all types), Kvaser USBcan Professional, Kvaser Memorator Professional, Kvaser Eagle and Kvaser Memorator Light. To write customer data use external tools.

Parameters:
[in]hndAn open handle to a CAN channel.
[in]userNumberAssigned by Kvaser.
[in]itemNumberMust be zero (reserved)
[out]dataA pointer to a buffer of up to 8 bytes where the result will be placed.
[in]bufsizThe size of the buffer that data points at.
Returns:
canOK (zero) if success
canERR_xxx (negative) if failure
Examples:
read_customer_data.c.
kvStatus kvReadTimer ( const int  hnd,
unsigned int *  time 
)
C#
static Canlib.canStatus kvReadTimer(int hnd, out int time);
Delphi
function kvReadTimer(handle: canHandle; var time: Cardinal): kvStatus;

The kvReadTimer reads the hardware clock on the specified device and returns the value.

When the call to kvReadTimer() returns, the time value is already obsolete. The time required for the device firmware, any intermediary buses (like USB,) and the operating system to return the time value is not defined.

This call should be used instead of canReadTimer() because it can return an error code if it fails.

Parameters:
[in]hndAn open handle to a CAN channel.
[out]timeA pointer to a 32-bit unsigned integer that will receive the time value.
Returns:
canOK (zero) if success
canERR_xxx (negative) if failure
See also:
canReadTimer(), kvReadTimer64()
kvStatus kvReadTimer64 ( const int  hnd,
1 *  time 
)
C#
static Canlib.canStatus kvReadTimer64(int hnd, out long time);
Delphi
function kvReadTimer64(handle: canHandle; var time: Int64): kvStatus;

The kvReadTimer64 reads the hardware clock on the specified device and returns the value.

When the call to kvReadTimer64() returns, the time value is already obsolete. The time required for the device firmware, any intermediary buses (like USB,) and the operating system to return the time value is not defined.

This call should be used instead of canReadTimer() because it can return an error code if it fails.

Parameters:
[in]hndAn open handle to a CAN channel.
[out]timeA pointer to a 64-bit signed integer that will receive the time value.
Returns:
canOK (zero) if success
canERR_xxx (negative) if failure
See also:
kvReadTimer(), canReadTimer()
canStatus kvSelfTest ( const int  hnd,
unsigned long *  presults 
)
C#
static Canlib.canStatus kvSelfTest(int hnd, out int presults);
Delphi
function kvSelfTest(handle: canHandle; var presults: Cardinal): canStatus;

The kvSelfTest function runs a built-in self test in the device. Note that not all devices supports built-in self tests.

Parameters:
[in]hndAn open hnd to a CAN channel.
[out]presultsA pointer to a 32-bit unsigned integer where the resuls of the self test will be placed.
Returns:
canOK (zero) if success
canERR_xxx (negative) if failure
kvStatus kvSetNotifyCallback ( const int  hnd,
kvCallback_t  callback,
void *  context,
unsigned int  notifyFlags 
)
C#
static Canlib.canStatus kvSetNotifyCallback(int hnd, Canlib.kvCallbackDelegate callback, IntPtr context, uint notifyFlags);
Delphi
function kvSetNotifyCallback(handle: canHandle; callback: kvCallback_t; context: Pointer; notifyFlags: Cardinal): canStatus;

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()