Functions
General
CANlib

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] | channel | The 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] | item | This parameter specifies what data to obtain for the specified channel. The value is one of the constants canCHANNELDATA_xxx.
  [out] | buffer | The address of a buffer which is to receive the data.
  [in] | bufsize | The 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] | err | The error code.
  [out] | buf | The buffer which is to receive the text, which is a zero-terminated string (provided the buffer is large enough.)
  [in] | bufsiz | The 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] | channelCount | A 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] | itemCode | Specifies 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] | hnd | A handle to an open circuit.
  [in] | func | A canIOCTL_xxx function code
  [in,out] | buf | Pointer 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] | buflen | The 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] | hnd | An open handle to a CAN channel.
  [out] | result | A 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] | hnd | An open handle to a CAN channel.
  [in] | mode | One 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] | action | One of the kvLED_ACTION_xxx constants, defining which LED to turn on or off.
  [in] | timeout | Specifies 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:

- hwType = canHWTYPE_MEMORATOR_PRO
- hwBusType = kvBUSTYPE_USB
- hwName = `"Kvaser Memorator Professional"`

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] | index | Use 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] | hwName | A pointer to a buffer that will receive the name of the hardware family, as a zero-terminated ASCII string.
  [in] | nameLen | The length of the hwName buffer.
  [out] | hwType | Pointer to a 32-bit integer that will receive the hardware type (one of the canHWTYPE_xxx constants.)
  [out] | hwBusType | Pointer 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] | hnd | An open handle to a CAN channel.
  [in] | userNumber | Assigned by Kvaser.
  [in] | itemNumber | Must be zero (reserved)
  [out] | data | A pointer to a buffer of up to 8 bytes where the result will be placed.
  [in] | bufsiz | The 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] | hnd | An open handle to a CAN channel.
  [out] | time | A 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] | hnd | An open handle to a CAN channel.
  [out] | time | A 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] | hnd | An open handle to a CAN channel.
  [in] | callback | A pointer to a callback function of type kvCallback_t
  [in] | context | A pointer to arbitrary user-defined context data which is passed to the callback function.
  [in] | notifyFlags | One or more of the canNOTIFY_xxx flags.

Returns
  canOK (zero) if success
  canERR_xxx (negative) if failure

See also
  canSetNotify()