Initialization, reading versions and other information. More...
Functions | |
void | canInitializeLibrary (void) |
canStatus | canEnumHardwareEx (int *channelCount) |
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) |
Initialization, reading versions and other information.
canStatus canEnumHardwareEx | ( | int * | channelCount | ) |
[out] | channelCount | Number of channels present. |
This function will re-enumerate all currently available CAN channels while not affecting already opened channel handles.
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.
[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. |
This function translates an error code (canERR_xxx) to a human-readable, English text.
[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. |
canStatus canGetNumberOfChannels | ( | int * | channelCount | ) |
This function returns the number of available CAN channels in the computer. The virtual channels are included in this number.
[out] | channelCount | A pointer to a DWORD which will receive the current number of channels. |
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.
unsigned int canGetVersionEx | ( | unsigned int | itemCode | ) |
This function returns various version numbers from the driver routines.
[in] | itemCode | Specifies which version number to retrieve. See canVERSION_CANLIB32_xxx |
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.
canStatus canIoCtl | ( | const int | hnd, |
unsigned int | func, | ||
void * | buf, | ||
unsigned int | buflen | ||
) |
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.
[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. |
BOOL canProbeVersion | ( | const int | hnd, |
int | major, | ||
int | minor, | ||
int | oem_id, | ||
unsigned int | flags | ||
) |
This function checks whether a specific version of CANlib is installed on the system.
The default behaviour of canProbeVersion is to accept
You get the default behaviour by setting flags to 0. Use any combination of the canVERSION_xxx flags to modify the behaviour.
[in] | hnd | A handle to an open circuit. |
[in] | major | The major version number of the version to test for. |
[in] | minor | The minor version number of the version to test for. |
[in] | oem_id | Reserved, must be zero. |
[in] | flags | Any combination of the canVERSION_xxx flags, or 0. |
canStatus canUnloadLibrary | ( | void | ) |
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:
canStatus kvAnnounceIdentity | ( | const int | hnd, |
void * | buf, | ||
size_t | bufsiz | ||
) |
The kvAnnounceIdentity function is used by certain OEM applications.
[in] | hnd | An open handle to a CAN channel. |
[out] | buf | A pointer to the data to be sent to the driver. |
[in] | bufsiz | The size, in bytes, of the buffer that buf points to. |
canStatus kvAnnounceIdentityEx | ( | const int | hnd, |
int | type, | ||
void * | buf, | ||
size_t | bufsiz | ||
) |
The kvAnnounceIdentityEx function is used by certain OEM applications.
[in] | hnd | An open handle to a CAN channel. |
[in] | type | Type of announcement. |
[out] | buf | A pointer to the data to be sent to the driver. |
[in] | bufsiz | The size, in bytes, of the buffer that buf points to. |
canStatus kvBeep | ( | const int | hnd, |
int | freq, | ||
unsigned int | duration | ||
) |
The kvBeep function emits a sound of a specific frequency and duration from the loudspeaker on the device.
[in] | hnd | An open handle to a CAN channel. |
[in] | freq | The frequency (in Hertz) of the sound. |
[in] | duration | The duration of the sound, in milliseconds. |
kvStatus kvDeviceGetMode | ( | const int | hnd, |
int * | result | ||
) |
The kvDeviceGetMode() reads the current device's specific mode.
[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. |
kvStatus kvDeviceSetMode | ( | const int | hnd, |
int | mode | ||
) |
The kvDeviceSetMode() sets the mode.
[in] | hnd | An open handle to a CAN channel. |
[in] | mode | One of the kvDEVICE_MODE_xxx constants, defining which mode to use. |
canStatus kvFlashLeds | ( | const int | hnd, |
int | action, | ||
int | timeout | ||
) |
The kvFlashLeds function will turn the LEDs on the device on or off.
[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. |
canStatus kvGetApplicationMapping | ( | int | busType, |
char * | appName, | ||
int | appChannel, | ||
int * | resultingChannel | ||
) |
busType | |
appName | |
appChannel | |
resultingChannel |
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:
"Kvaser Memorator Professional"
This means that
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.
[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.) |
kvStatus kvPingGetLatest | ( | const int | hnd, |
unsigned int * | requestTime, | ||
unsigned int * | pingTime | ||
) |
This retrieves the latest ping time issued by an earlier call to kvPingRequest()
[in] | hnd | A handle to an open circuit. |
[out] | requestTime | Time of request in microseconds. Used for matching answer to request. |
[out] | pingTime | Latest value of ping time in milliseconds. |
kvStatus kvPingRequest | ( | const int | hnd, |
unsigned int * | requestTime | ||
) |
This function sends an active ping to a device. The ping time can later be retrieved using kvPingGetLatest().
[in] | hnd | A handle to an open circuit. |
[out] | requestTime | Time of request in microseconds. Used for matching answer to request. |
kvStatus kvReadDeviceCustomerData | ( | const int | 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.
[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. |
kvStatus kvReadTimer | ( | const int | 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.
[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. |
kvStatus kvReadTimer64 | ( | const int | hnd, |
int64_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.
[in] | hnd | An open handle to a CAN channel. |
[out] | time | A pointer to a 64-bit signed integer that will receive the time value. |
canStatus kvSelfTest | ( | const int | hnd, |
unsigned long * | presults | ||
) |
The kvSelfTest function runs a built-in self test in the device. Note that not all devices supports built-in self tests.
[in] | hnd | An open hnd to a CAN channel. |
[out] | presults | A pointer to a 32-bit unsigned integer where the results of the self test will be placed. |
kvStatus kvSetNotifyCallback | ( | const int | 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.
[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. |