General

Initialization, reading versions and other information. More...

Functions

void canInitializeLibrary (void)
 
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 canGetNumberOfChannels (int *channelCount)
 
canStatus canGetChannelData (int channel, int item, void *buffer, size_t bufsize)
 
unsigned int canGetVersionEx (unsigned int itemCode)
 
canStatus canUnloadLibrary (void)
 
canStatus kvFlashLeds (const CanHandle hnd, int action, int timeout)
 
kvStatus kvSetNotifyCallback (const CanHandle hnd, kvCallback_t callback, void *context, unsigned int notifyFlags)
 
kvStatus kvGetSupportedInterfaceInfo (int index, char *hwName, size_t nameLen, int *hwType, int *hwBusType)
 
kvStatus kvReadDeviceCustomerData (const CanHandle hnd, int userNumber, int itemNumber, void *data, size_t bufsiz)
 
kvStatus kvDeviceSetMode (const CanHandle hnd, int mode)
 
kvStatus kvDeviceGetMode (const CanHandle hnd, int *result)
 
kvStatus kvReadTimer (const CanHandle hnd, unsigned int *time)
 
kvStatus kvReadTimer64 (const CanHandle hnd, uint64_t *time)
 

Detailed Description

Initialization, reading versions and other information.

Function Documentation

◆ canGetChannelData()

canStatus canGetChannelData ( int  channel,
int  item,
void *  buffer,
size_t  bufsize 
)

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
canGetChannelData Example
canGetNumberOfChannels()
Examples:
listChannels.c.

◆ canGetErrorText()

canStatus canGetErrorText ( canStatus  err,
char *  buf,
unsigned int  bufsiz 
)

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
canGetErrorText Example
Examples:
busparms.c, cancount.c, canfdmonitor.c, canfdwrite.c, canmonitor.c, listChannels.c, readTimerTest.c, simplewrite.c, and writeloop.c.

◆ canGetNumberOfChannels()

canStatus canGetNumberOfChannels ( int *  channelCount)

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
canGetChannelData Example, Virtual Channels
canGetChannelData()
Examples:
listChannels.c.

◆ canGetVersion()

unsigned short canGetVersion ( void  )

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
Note
Linux returns version number from libcanlib.so
See also
Version Checking
canGetVersionEx()

◆ canGetVersionEx()

unsigned int canGetVersionEx ( unsigned int  itemCode)

This function returns various version numbers from the driver routines.

Parameters
[in]itemCodeSpecifies which version number to retrieve. See canVERSION_CANLIB32_xxx
Returns
The return value is desired version number.
See also
Version Checking
Examples:
listChannels.c.

◆ canInitializeLibrary()

void canInitializeLibrary ( void  )

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
canInitializeLibrary Example
Examples:
busparms.c, cancount.c, canfdmonitor.c, canfdwrite.c, canmonitor.c, listChannels.c, readTimerTest.c, simplewrite.c, and writeloop.c.

◆ canIoCtl()

canStatus canIoCtl ( const CanHandle  hnd,
unsigned int  func,
void *  buf,
unsigned int  buflen 
)

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

◆ canUnloadLibrary()

canStatus canUnloadLibrary ( void  )

canUnloadLibrary() will close all open handles and free allocated memory.

Calling canUnloadLibrary() makes any open CanHandle invalid. The proper procedure for using canUnloadLibrary() is:

  1. Close all active handles using canBusOff() and canClose().
  2. At this point all handles earlier returned by canOpenChannel() should be freed.
  3. Call canUnloadLibrary().
  4. Call canInitializeLibrary().
  5. You can now setup your handles to Kvaser devices from scratch (ie. canOpenChannel(), canSetBusParams(), canBusOn(), etc).
Returns
canOK (zero) if success
canERR_xxx (negative) if failure
See also
canInitializeLibrary()
Examples:
busparms.c, cancount.c, canfdmonitor.c, canfdwrite.c, canmonitor.c, listChannels.c, readTimerTest.c, simplewrite.c, and writeloop.c.

◆ kvDeviceGetMode()

kvStatus kvDeviceGetMode ( const CanHandle  hnd,
int *  result 
)

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

◆ kvDeviceSetMode()

kvStatus kvDeviceSetMode ( const CanHandle  hnd,
int  mode 
)

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

◆ kvFlashLeds()

canStatus kvFlashLeds ( const CanHandle  hnd,
int  action,
int  timeout 
)

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

◆ kvGetSupportedInterfaceInfo()

kvStatus kvGetSupportedInterfaceInfo ( int  index,
char *  hwName,
size_t  nameLen,
int *  hwType,
int *  hwBusType 
)

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.

Note
Not inplemented in linux.
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()

◆ kvReadDeviceCustomerData()

kvStatus kvReadDeviceCustomerData ( const CanHandle  hnd,
int  userNumber,
int  itemNumber,
void *  data,
size_t  bufsiz 
)

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.

Note
Not implemented in linux.
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

◆ kvReadTimer()

kvStatus kvReadTimer ( const CanHandle  hnd,
unsigned int *  time 
)

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

◆ kvReadTimer64()

kvStatus kvReadTimer64 ( const CanHandle  hnd,
uint64_t *  time 
)

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 unsigned integer that will receive the time value.
Returns
canOK (zero) if success
canERR_xxx (negative) if failure
See also
kvReadTimer(), canReadTimer()

◆ kvSetNotifyCallback()

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

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