canGetChannelData

Syntax


#include <canlib.h>
canStatus canGetChannelData(int channel, int item, 
                            void *buffer, size_t bufsize);

Description

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

Parameters
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. Note: you must pass a channel number and not a channel handle.
item
This parameter specifies what data to obtain for the specified channel. The value is one of the constants canCHANNELDATA_xxx; see below.
buffer
The address of a buffer which is to receive the data.
bufsize
The size of the buffer to which the buffer parameter points.
Values of the item parameter

canCHANNELDATA_CHANNEL_CAP
buffer points to a 32-bit unsigned integer that receives the capabilities of the CAN controller; this is a combination of the canCHANNEL_CAP_xxx flags.

 

canCHANNELDATA_TRANS_CAP
buffer points to a 32-bit unsigned integer that receives the capabilities of the CAN transceiver; this is a combination of the canDRIVER_CAP_xxx flags.

 

canCHANNELDATA_CHANNEL_FLAGS
Currently not implemented.

 

canCHANNELDATA_CARD_TYPE
buffer points to a 32-bit unsigned integer that receives the hardware type of the card. This value is any one of the canHWTYPE_xxx constants.

 

canCHANNELDATA_CARD_NUMBER
buffer points to a 32-bit unsigned integer that receives the card's number in the computer. Each card type is numbered separately. For example, the first LAPcan card in a machine will have number 0, the second LAPcan number 1, etc.

 

canCHANNELDATA_CHAN_NO_ON_CARD
buffer points to a 32-bit unsigned integer which receives the channel number on the card.

 

canCHANNELDATA_CARD_SERIAL_NO
buffer points to a 64-bit (8 bytes) area which receives the serial number of the card. If the card doesn't have a serial number, 0 is returned. The serial number is an 8-byte unsigned integer. Currently, no products are using all 8 bytes; at most 4 bytes are used.

 

canCHANNELDATA_TRANS_SERIAL_NO
buffer points to a 64-bit (8 bytes) area which receives the serial number of the transceiver. The serial number is an 8-byte unsigned integer. If the transceiver doesn't have a serial number, 0 is returned.

 

canCHANNELDATA_CARD_FIRMWARE_REV
buffer points to a 64-bit (8 bytes) area which receives the firmware revision number on the card. This number consists of four 16-bit words: the major revision, the minor revision, the release number and the build number, listed in order from the most significant to the least significant.

 

canCHANNELDATA_CARD_HARDWARE_REV
buffer points to a 64-bit (8 bytes) area which receives the hardware revision number on the card. This number consists of four 16-bit words; the two most significant are always 0, and the two least significant are the major revision and the minor revision, listed in order from the most significant to the least significant.

 

canCHANNELDATA_CARD_UPC_NO
buffer points to a 8-byte area which receives the UPC (EAN) number for the card. If there is no UPC number, the buffer is filled with zeros. The UPC (EAN) number is coded as a BCD string with the LSB first, so e.g. 733-0130-00122-0 is coded as 0x30001220 0x00073301.

 

canCHANNELDATA_TRANS_UPC_NO
buffer points to a 8-byte area which receives the UPC (EAN) number for the transceiver. If there is no UPC number, the buffer is filled with zeros. The UPC (EAN) number is coded as a BCD string with the LSB first, so e.g. 733-0130-00122-0 is coded as 0x30001220 0x00073301.

 

canCHANNELDATA_CHANNEL_NAME
buffer points to an area which receives a zero-terminated string with a clear-text name of the channel.
Note: use of this item code is no longer recommended. The returned channel name doesn't contain the exact hardware type (it just contains the device family) and uses zero-based channel numbering, which is not user friendly. Instead, use e.g. canCHANNELDATA_DEVDESCR_ASCII and canCHANNELDATA_CHAN_NO_ON_CARD to build your own channel name.

 

canCHANNELDATA_DLL_FILE_VERSION
buffer points to an array of 4 16-bit unsigned integers which receives the file version number of the second-level DLL driver file, i.e. the DLL that interfaces between CANLIB32.DLL and the driver proper.

Index in bufferContents
00
1The build number
2The minor revision number
3The major revision number

canCHANNELDATA_DLL_PRODUCT_VERSION
buffer points to an array of 4 16-bit unsigned integers which receives the product version number of the second-level DLL driver file, i.e. the DLL that interfaces between CANLIB32.DLL and the driver proper.

Index in bufferContents
00
10
2The minor revision number
3The major revision number

canCHANNELDATA_DLL_FILETYPE
buffer points to a 32-bit unsigned integer which receives a number that identifies the second-level DLL driver file, i.e. the DLL that interfaces between CANLIB32.DLL and the driver proper.

ValueMeaning
1kvalapw.dll - used with CANLIB up to 2.29 together with the Windows 95/98/ME VxD and the NT 4.0 VCAN driver.
2kvalapw2.dll - used with CANLIB from 3.0 and on together with the WDM and Windows 2000/XP drivers.

canCHANNELDATA_TRANS_TYPE
buffer points to a 32-bit unsigned integer which receives the CAN transceiver type of the specified channel. This value is one of the canTRANSCEIVER_TYPE_xxx constants.

 

canCHANNELDATA_DEVICE_PHYSICAL_POSITION
(Windows 2000, XP and later only) buffer points to a 32-bit unsigned integer which receives an address indicating where the device is located on its underlying bus. The interpretation of this number is bus-specific. If the address is unknown or the bus driver does not support an address, the bus driver leaves this member at its default value of 0xFFFFFFFF.

The following list describes the information certain bus drivers store in the Address field for their child devices:

  • ISA: Does not supply an address. Defaults to 0xFFFFFFFF.
  • PC Card (PCMCIA): The socket number (typically 0x00 or 0x40).
  • PCI: The device number in the high word and the function number in the low word.
  • USB: The port number.
canCHANNELDATA_UI_NUMBER
(Windows 2000, XP and later only) buffer points to a 32-bit unsigned integer which receives a number associated with the device that can be displayed in the user interface. This number is typically a user-perceived slot number, such as a number printed next to the slot on the board, or some other number that makes locating the physical device easier for the user. For buses with no such convention, or when the UI number is unknown, 0xFFFFFFFF is returned.

 

canCHANNELDATA_TIMESYNC_ENABLED
(Not supported on Windows 95) 
buffer points to a 32-bit unsigned integer which is set to 0, if the legacy time synchronization is not currently enabled for the specified channel, and 1, if the legacy time synchronization is currently enabled for the specified channel.

Note: legacy time synchronization is a mechanism that will keep the PC and CAN channel clocks in sync. The synchronization is done in the driver, which periodically calculates the difference between the PC clock and the CAN device clock and compensates for the clock drift by recalculating the CAN message time stamps. You need to enable clock synchronization in the Control Panel using the Kvaser Hardware applet.

Legacy time synchronization is implemented only on LAPcan and LAPcan II. It is not related to Kvaser MagiSync™ which is implemented in the high-end members of the Kvaser Leaf family. Kvaser MagiSync is always enabled and allows for much more accurate time synchronization.

 

canCHANNELDATA_DRIVER_FILE_VERSION
buffer points to an array of four 16-bit unsigned integers which receives the file version number of the kernel-mode driver.

Index in bufferContents
0The build number
10
2The minor revision number
3The major revision number

canCHANNELDATA_DRIVER_PRODUCT_VERSION
buffer points to an array of four 16-bit unsigned integers which receives the product version number of the kernel-mode driver.

Index in bufferContents
00
10
2The minor revision number
3The major revision number

canCHANNELDATA_MFGNAME_UNICODE
buffer points to a buffer which receives the device manufacturer's name as a zero-terminated Unicode string.

canCHANNELDATA_MFGNAME_ASCII
buffer points to a buffer which receives the device manufacturer's name as a zero-terminated ASCII string.

canCHANNELDATA_DEVDESCR_UNICODE
buffer points to a buffer which receives the product name of the device as a zero-terminated Unicode string.

canCHANNELDATA_DEVDESCR_ASCII
buffer points to a buffer which receives the product name of the device as a zero-terminated ASCII string.

Return Value

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

Related Topics

canGetNumberOfChannels

An example.