Kvaser Linux CANLIB

General

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)

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 CanHandle hnd, kvCallback_t callback, void *context, unsigned int notifyFlags)

Function Documentation

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.
[in,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:
listChannels.c.
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.
[in,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:
busparms.c, cancount.c, opentest.c, readTimerTest.c, and simplewrite.c.
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:
Code Examples, Virtual Channels
canGetChannelData()
Examples:
listChannels.c.
unsigned short canGetVersion ( void  )

This API call returns the version of the CANLIB API library (libcanlib.so.x.y). The most significant byte is the major version number and the least significant byte is the minor version number.

Returns:
version number of libcanlib.so.x.y
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.

Note:
This call replaces the canLocateHardware() API call and serves the same purpose.
See also:
Code Examples
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
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()