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 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)
 
unsigned int canGetVersionEx (unsigned int itemCode)
 
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 kvSetNotifyCallback (const int 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 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)
 
kvStatus kvReadTimer (const int hnd, unsigned int *time)
 
kvStatus kvReadTimer64 (const int hnd, int64_t *time)
 

Detailed Description

Initialization, reading versions and other information.

Function Documentation

◆ canGetChannelData()

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: size_t): 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
Channel Information
canGetNumberOfChannels()
Examples:
example/c/channeldata.c, example/c/kvrConfig.c, example/c/kvrConnect.c, example/c/kvrNetworkConnectionTest.c, example/cpp/candemo/candemo.cpp, and how-to/c/listChannels.c.

◆ canGetErrorText()

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
Error checking
Examples:
example/c/candump.c, example/c/canecho.c, example/c/channeldata.c, example/c/gensig/gensig.c, example/c/thread.c, example/c/tx.c, example/cpp/candemo/candemo.cpp, how-to/c/listChannels.c, how-to/c/openChannels.c, tutorial/c/MonitorCanChannel.c, and tutorial/c/SendMessage.c.

◆ canGetNumberOfChannels()

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
Channel Information, Virtual Channels
canGetChannelData()
Examples:
example/c/channeldata.c, example/c/kvrConfig.c, example/c/kvrConnect.c, example/c/kvrNetworkConnectionTest.c, example/cpp/candemo/candemo.cpp, and how-to/c/listChannels.c.

◆ canGetVersion()

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

◆ canGetVersionEx()

unsigned int canGetVersionEx ( unsigned int  itemCode)
C#
static int canGetVersionEx(int itemCode);
Delphi
function canGetVersionEx(itemCode: Cardinal): Cardinal;

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

◆ canInitializeLibrary()

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
Initialization
Examples:
example/c/candump.c, example/c/canecho.c, example/c/channeldata.c, example/c/gensig/gensig.c, example/c/kvrConfig.c, example/c/kvrConnect.c, example/c/kvrNetworkConnectionTest.c, example/c/read_customer_data.c, example/c/thread.c, example/c/tscript/envvar/envvar.c, example/c/tx.c, example/cpp/candemo/candemo.cpp, tutorial/c/MonitorCanChannel.c, and tutorial/c/SendMessage.c.

◆ canIoCtl()

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 (canIOCTL_xxx). 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:
example/c/gensig/gensig.c, example/c/kvrConfig.c, and example/cpp/candemo/candemo.cpp.

◆ canProbeVersion()

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
canGetVersion(), canGetVersionEx(), canGetChannelData()

◆ canUnloadLibrary()

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.

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:
example/c/kvrConfig.c.

◆ kvAnnounceIdentity()

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: size_t): 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

◆ kvAnnounceIdentityEx()

canStatus kvAnnounceIdentityEx ( const int  hnd,
int  type,
void *  buf,
size_t  bufsiz 
)
C#
static Canlib.canStatus kvAnnounceIdentity(int hnd, int type, object buffer);
Delphi
function kvAnnounceIdentity(handle: canHandle; tp: Integer; var buf; bufsiz: size_t): canStatus;

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

◆ kvBeep()

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

◆ kvDeviceGetMode()

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

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

◆ kvFlashLeds()

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

◆ kvGetApplicationMapping()

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

◆ kvGetSupportedInterfaceInfo()

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: size_t; 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.

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

◆ kvPingGetLatest()

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

◆ kvPingRequest()

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

◆ kvReadDeviceCustomerData()

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: size_t): 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.

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
Examples:
example/c/read_customer_data.c.

◆ kvReadTimer()

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

◆ kvReadTimer64()

kvStatus kvReadTimer64 ( const int  hnd,
int64_t *  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()

◆ kvSelfTest()

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 results of the self test will be placed.
Returns
canOK (zero) if success
canERR_xxx (negative) if failure

◆ kvSetNotifyCallback()

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