Functions
CAN
CANlib

CAN related functions. More...

## Functions
canStatus | canClose (const CanHandle hnd)
canStatus | canBusOn (const CanHandle hnd)
canStatus | canBusOff (const CanHandle hnd)
canStatus | canSetBusParams (const CanHandle hnd, long freq, unsigned int tseg1, unsigned int tseg2, unsigned int sjw, unsigned int noSamp, unsigned int syncmode)
canStatus | canSetBusParamsFd (const CanHandle hnd, long freq_brs, unsigned int tseg1_brs, unsigned int tseg2_brs, unsigned int sjw_brs)
canStatus | canGetBusParams (const CanHandle hnd, long *freq, unsigned int *tseg1, unsigned int *tseg2, unsigned int *sjw, unsigned int *noSamp, unsigned int *syncmode)
canStatus | canGetBusParamsFd (const CanHandle hnd, long *freq_brs, unsigned int *tseg1_brs, unsigned int *tseg2_brs, unsigned int *sjw_brs)
canStatus | canSetBusOutputControl (const CanHandle hnd, const unsigned int drivertype)
canStatus | canGetBusOutputControl (const CanHandle hnd, unsigned int *drivertype)
canStatus | canAccept (const CanHandle hnd, const long envelope, const unsigned int flag)
canStatus | canReadStatus (const CanHandle hnd, unsigned long *const flags)
canStatus | canReadErrorCounters (const CanHandle hnd, unsigned int *txErr, unsigned int *rxErr, unsigned int *ovErr)
canStatus | canWrite (const CanHandle hnd, long id, void *msg, unsigned int dlc, unsigned int flag)
canStatus | canWriteSync (const CanHandle hnd, unsigned long timeout)
canStatus | canRead (const CanHandle hnd, long *id, void *msg, unsigned int *dlc, unsigned int *flag, unsigned long *time)
canStatus | canReadWait (const CanHandle hnd, long *id, void *msg, unsigned int *dlc, unsigned int *flag, unsigned long *time, unsigned long timeout)
canStatus | canReadSpecific (const CanHandle hnd, long id, void *msg, unsigned int *dlc, unsigned int *flag, unsigned long *time)
canStatus | canReadSync (const CanHandle hnd, unsigned long timeout)
canStatus | canReadSyncSpecific (const CanHandle hnd, long id, unsigned long timeout)
canStatus | canReadSpecificSkip (const CanHandle hnd, long id, void *msg, unsigned int *dlc, unsigned int *flag, unsigned long *time)
canStatus | canSetNotify (const CanHandle hnd, void(*callback)(canNotifyData *), unsigned int notifyFlags, void *tag)
canStatus | canGetRawHandle (const CanHandle hnd, void *pvFd)
canStatus | canTranslateBaud (long *const freq, unsigned int *const tseg1, unsigned int *const tseg2, unsigned int *const sjw, unsigned int *const nosamp, unsigned int *const syncMode)
CanHandle | canOpenChannel (int channel, int flags)
canStatus | canSetBusParamsC200 (const CanHandle hnd, unsigned char btr0, unsigned char btr1)
canStatus | canSetDriverMode (const CanHandle hnd, int lineMode, int resNet)
canStatus | canGetDriverMode (const CanHandle hnd, int *lineMode, int *resNet)
canStatus | canResetBus (const CanHandle hnd)
canStatus | canWriteWait (const CanHandle hnd, long id, void *msg, unsigned int dlc, unsigned int flag, unsigned long timeout)
canStatus | canSetAcceptanceFilter (const CanHandle hnd, unsigned int code, unsigned int mask, int is_extended)
canStatus | canFlushReceiveQueue (const CanHandle hnd)
canStatus | canFlushTransmitQueue (const CanHandle hnd)
canStatus | canRequestChipStatus (const CanHandle hnd)
canStatus | canRequestBusStatistics (const CanHandle hnd)
canStatus | canGetBusStatistics (const CanHandle hnd, canBusStatistics *stat, size_t bufsiz)
canStatus | canGetHandleData (const CanHandle hnd, int item, void *buffer, size_t bufsize)

## Detailed Description

CAN related functions.

## Function Documentation

## ◆ canAccept()

canStatus canAccept | ( | const CanHandle | hnd,
|  | const long | envelope,
|  | const unsigned int | flag
| ) |  |

This routine sets the message acceptance filters on a CAN channel.

On some boards the acceptance filtering is done by the CAN hardware; on other boards (typically those with an embedded CPU,) the acceptance filtering is done by software. canAccept() behaves in the same way for all boards, however.

canSetAcceptanceFilter() and canAccept() both serve the same purpose but the former can set the code and mask in just one call.

If you want to remove a filter, call canAccept() with the mask set to 0.

Note
  You can set the extended code and mask only on CAN boards that support extended identifiers.
  Not all CAN boards support different masks for standard and extended CAN identifiers.

Parameters

  [in] | hnd | An open handle to a CAN circuit.
  [in] | envelope | The mask or code to set.
  [in] | flag | Any of canFILTER_SET_CODE_STD, canFILTER_SET_MASK_STD, canFILTER_SET_CODE_EXT or canFILTER_SET_MASK_EXT

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

See also
  Message Filters, Code and Mask Format, canAccept / canSetAcceptanceFilter Example

## ◆ canBusOff()

canStatus canBusOff | ( | const CanHandle | hnd | ) |

Takes the specified channel off-bus.

Parameters

  [in] | hnd | An open handle to a CAN channel.

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

See also
  canBusOff Example
  canBusOn(), canResetBus()

Examples:
  cancount.c, canfdmonitor.c, canfdwrite.c, canmonitor.c, simplewrite.c, and writeloop.c.

## ◆ canBusOn()

canStatus canBusOn | ( | const CanHandle | hnd | ) |

Takes the specified channel on-bus.

If you are using multiple handles to the same physical channel, for example if you are writing a threaded application, you must call canBusOn() once for each handle. The same applies to canBusOff() - the physical channel will not go off bus until the last handle to the channel goes off bus.

Parameters

  [in] | hnd | An open handle to a CAN channel.

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

See also
  canBusOn Example
  canBusOff(), canResetBus()

Examples:
  cancount.c, canfdmonitor.c, canfdwrite.c, canmonitor.c, simplewrite.c, and writeloop.c.

## ◆ canClose()

canStatus canClose | ( | const CanHandle | hnd | ) |

Closes the channel associated with the handle. If no other threads are using the CAN circuit, it is taken off bus. The handle can not be used for further references to the channel, so any variable containing it should be zeroed.

canClose() will almost always return canOK; the specified handle is closed on an best-effort basis.

Parameters

  [in] | hnd | An open handle to a CAN channel.

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

See also
  canClose Example
  canOpenChannel(), canBusOn(), canBusOff()

Examples:
  cancount.c, canfdmonitor.c, canfdwrite.c, canmonitor.c, readTimerTest.c, simplewrite.c, and writeloop.c.

## ◆ canFlushReceiveQueue()

canStatus canFlushReceiveQueue | ( | const CanHandle | hnd | ) |

This function removes all received messages from the handle's receive queue. Other handles open to the same channel are not affected by this operation. That is, only the messages belonging to the handle you are passing to canFlushReceiveQueue are discarded.

Note
  This call has the same effect as calling canIoCtl() with a function code of canIOCTL_FLUSH_RX_BUFFER.

Parameters

  [in] | hnd | A handle to an open circuit.

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

See also
  canFlushTransmitQueue()

## ◆ canFlushTransmitQueue()

canStatus canFlushTransmitQueue | ( | const CanHandle | hnd | ) |

This function removes all messages pending transmission from the transmit queue of the circuit.

Note
  If there are other handles open to the same circuit, they are also flushed.
  This call has the same effect as calling canIoCtl() with a function code of canIOCTL_FLUSH_TX_BUFFER.

Parameters

  [in] | hnd | A handle to an open circuit.

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

See also
  canFlushReceiveQueue()

## ◆ canGetBusOutputControl()

canStatus canGetBusOutputControl | ( | const CanHandle | hnd,
|  | unsigned int * | drivertype
| ) |  |

This function retrieves the current CAN controller driver type. This corresponds loosely to the bus output control register in the CAN controller, hence the name of this function. CANlib does not allow for direct manipulation of the bus output control register; instead, symbolic constants are used to select the desired driver type.

Note
  Don't confuse the CAN controller driver type with the bus driver type. The CAN controller is not connected directly to the CAN bus; instead, it is connected to a bus transceiver circuit which interfaces directly to the bus. The "CAN controller driver type" we are talking about here refers to the mode which the CAN controller uses to drive the bus transceiver circuit.
  Silent Mode is not supported by all CAN controllers.

Parameters

  [in] | hnd | An open handle to a CAN circuit.
  [out] | drivertype | A pointer to an unsigned int which receives the current driver type. The driver type can be either canDRIVER_NORMAL or canDRIVER_SILENT.

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

See also
  canSetBusOutputControl()

## ◆ canGetBusParams()

canStatus canGetBusParams | ( | const CanHandle | hnd,
|  | long * | freq,
|  | unsigned int * | tseg1,
|  | unsigned int * | tseg2,
|  | unsigned int * | sjw,
|  | unsigned int * | noSamp,
|  | unsigned int * | syncmode
| ) |  |

This function retrieves the current nominal bus parameters for the specified channel.

The anatomy of a CAN bit is discussed in detail at Kvaser's web site at www.kvaser.com.

Parameters

  [in] | hnd | An open handle to a CAN controller.
  [out] | freq | Bit rate (bits per second).
  [out] | tseg1 | Time segment 1, that is, the number of quanta from (but not including) the Sync Segment to the sampling point.
  [out] | tseg2 | Time segment 2, that is, the number of quanta from the sampling point to the end of the bit.
  [out] | sjw | The Synchronization Jump Width.
  [out] | noSamp | The number of sampling points; can be 1 or 3.
  [out] | syncmode | Unsupported, always read as one.

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

See also
  Bit Rate Examples, Bit Rate and Other Bus Parameters
  canSetBusParams(), canSetBusParamsC200()

Examples:
  busparms.c.

## ◆ canGetBusParamsFd()

canStatus canGetBusParamsFd | ( | const CanHandle | hnd,
|  | long * | freq_brs,
|  | unsigned int * | tseg1_brs,
|  | unsigned int * | tseg2_brs,
|  | unsigned int * | sjw_brs
| ) |  |

This function retrieves the current data bus parameters for the specified CAN FD channel.

Parameters

  [in] | hnd | An open handle to a CAN FD controller.
  [out] | freq_brs | Bit rate (bits per second).
  [out] | tseg1_brs | Time segment 1, that is, the number of quanta from (but not including) the Sync Segment to the sampling point.
  [out] | tseg2_brs | Time segment 2, that is, the number of quanta from the sampling point to the end of the bit.
  [out] | sjw_brs | The Synchronization Jump Width.

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

## ◆ canGetBusStatistics()

canStatus canGetBusStatistics | ( | const CanHandle | hnd,
|  | canBusStatistics * | stat,
|  | size_t | bufsiz
| ) |  |

The canGetBusStatistics() function retrieves the latest bus statistics figures reported by the driver. You request the bus statistics from the driver by calling the canRequestBusStatistics() function.

Parameters

  [in] | hnd | An open handle to a CAN channel.
  [out] | stat | A pointer to a canBusStatistics struct that will receive the bus statistics figures.
  [in] | bufsiz | The size, in bytes, of the stat buffer.

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

See also
  canRequestBusStatistics()

## ◆ canGetDriverMode()

canStatus canGetDriverMode | ( | const CanHandle | hnd,
|  | int * | lineMode,
|  | int * | resNet
| ) |  |

This function retrieves the current CAN bus driver mode. This is typically a mode like sleep, wakeup, standby, fast mode, etc. The different modes are almost always hardware dependent and requires special DRVcan cables. As an example, the DRVcan S implements J2411 compliant single-wire CAN and supports four line modes, namely Normal, Sleep, Fast and Wakeup.

Standard ISO 11898 CAN do not support any of these bus driver modes.

Note
  The bus driver mode is typically used to control things like one- or two-wire mode, sleep mode, and so on. It requires special support in the CAN driver circuit.

Parameters

  [in] | hnd | An open handle to a CAN circuit.
  [out] | lineMode | A pointer to an int which receives the current line mode (canTRANSCEIVER_LINEMODE_xxx).
  [out] | resNet | A pointer to an int which receives the current resnet mode. This value is usually canTRANSCEIVER_RESNET_NA except for special DRVcan cables.

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

See also
  canSetDriverMode()

Note
  Not implemented in linux.

## ◆ canGetHandleData()

canStatus canGetHandleData | ( | const CanHandle | hnd,
|  | int | item,
|  | void * | buffer,
|  | size_t | bufsize
| ) |  |

Note
  This function can be used to retrieve certain pieces of information about an open handle to a CANlib channel.

Parameters

  [in] | hnd | An open handle to a CAN channel.
  [in] | item | This parameter specifies what data to obtain for the specified handle. 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()

## ◆ canGetRawHandle()

canStatus canGetRawHandle | ( | const CanHandle | hnd,
|  | void * | pvFd
| ) |  |

Returns raw handle/file descriptor for use in system calls.

Note
  Use this function with caution.

Parameters

  [in] | hnd | CanHandle
  [out] | pvFd | Pointer to raw can data.

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

## ◆ canOpenChannel()

CanHandle canOpenChannel | ( | int | channel,
|  | int | flags
| ) |  |

Opens a CAN channel (circuit) and returns a handle which is used in subsequent calls to CANlib.

Channel numbering is dependent on the installed hardware. The first channel always has number 0.

For example,

- If you have a single LAPcan, the channels are numbered 0 and 1.

- If you have a USBcan Professional, the channels are numbered 0-1 according to the labels on the cables.

- The virtual channels come after all physical channels.

If you are using multiple threads, note that the returned handle is usable only in the context of the thread that created it. That is, you must call canOpenChannel() in each of the threads in your application that uses the CAN bus. You can open the same channel from multiple threads, but you must call canOpenChannel() once per thread.

If you are using the same channel via multiple handles, note that the default behaviour is that the different handles will "hear" each other just as if each handle referred to a channel of its own. If you open, say, channel 0 from thread A and thread B and then send a message from thread A, it will be "received" by thread B. This behaviour can be changed using canIOCTL_SET_LOCAL_TXECHO.

Note
  The handle returned may be zero which is perfectly valid.

Parameters

  [in] | channel | The number of the channel. Channel numbering is hardware dependent.
  [in] | flags | A combination of canOPEN_xxx flags

Returns
  Returns a handle to the opened circuit, or canERR_xxx (negative) if the call failed.

See also
  canOpenChannel Example, Virtual Channels
  canGetNumberOfChannels(), canGetChannelData(), canIoCtl()

Examples:
  busparms.c, cancount.c, canfdmonitor.c, canfdwrite.c, canmonitor.c, readTimerTest.c, simplewrite.c, and writeloop.c.

## ◆ canRead()

canStatus canRead | ( | const CanHandle | hnd,
|  | long * | id,
|  | void * | msg,
|  | unsigned int * | dlc,
|  | unsigned int * | flag,
|  | unsigned long * | time
| ) |  |

Reads a message from the receive buffer. If no message is available, the function returns immediately with return code canERR_NOMSG.

If you are using the same channel via multiple handles, note that the default behaviour is that the different handles will "hear" each other just as if each handle referred to a channel of its own. If you open, say, channel 0 from thread A and thread B and then send a message from thread A, it will be "received" by thread B. This behaviour can be changed using canIOCTL_SET_LOCAL_TXECHO.

It is allowed to pass `NULL` as the value of id, msg, dlc, flag, and time.

Parameters

  [in] | hnd | A handle to an open circuit.
  [out] | id | Pointer to a buffer which receives the CAN identifier. This buffer will only get the identifier. To determine whether this identifier was standard (11-bit) or extended (29-bit), and/or whether it was remote or not, or if it was an error frame, examine the contents of the flag argument.
  [out] | msg | Pointer to the buffer which receives the message data. This buffer must be large enough (i.e. 8 bytes for classic CAN and up to 64 bytes for CAN FD).
  [out] | dlc | Pointer to a buffer which receives the message length.
  [out] | flag | Pointer to a buffer which receives the message flags, which is a combination of the canMSG_xxx (including canFDMSG_xxx if the CAN FD protocol is enabled) and canMSGERR_xxx values.
  [out] | time | Pointer to a buffer which receives the message time stamp.

Returns
  canOK (zero) if a message was read.
  canERR_NOMSG (negative) if there was no message available.
  canERR_xxx (negative) if failure

See also
  Reading Messages, Message Mailboxes, canRead Example, Time Stamping Accuracy and Resolution
  canReadSpecific(), canReadSpecificSkip(), canReadSync(), canReadSyncSpecific(), canReadWait()

## ◆ canReadErrorCounters()

canStatus canReadErrorCounters | ( | const CanHandle | hnd,
|  | unsigned int * | txErr,
|  | unsigned int * | rxErr,
|  | unsigned int * | ovErr
| ) |  |

Reads the error counters of the CAN controller.

canReadErrorCounters() returns the latest known values of the error counters in the specified circuit. If the error counters change values precisely when canReadErrorCounters() is called, it may not be reflected in the returned result.

It is allowed to pass `NULL` as the value of the txErr, rxErr, and ovErr parameters.

Use canIoCtl() to clear the counters.

Note
  Not all CAN controllers provide access to the error counters; in this case, an educated guess is returned.

Parameters

  [in] | hnd | A handle to an open circuit.
  [out] | txErr | A pointer to a `DWORD` which receives the transmit error counter.
  [out] | rxErr | A pointer to a `DWORD` which receives the receive error counter.
  [out] | ovErr | A pointer to a `DWORD` which receives the number of overrun errors.

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

See also
  canIoCtl()

## ◆ canReadSpecific()

canStatus canReadSpecific | ( | const CanHandle | hnd,
|  | long | id,
|  | void * | msg,
|  | unsigned int * | dlc,
|  | unsigned int * | flag,
|  | unsigned long * | time
| ) |  |

Reads a message with a specified identifier from the receive buffer. Any preceding message not matching the specified identifier will be kept in the receive buffer. If no message with the specified identifier is available, the function returns immediately with an error code.

If you are using the same channel via multiple handles, note that the default behaviour is that the different handles will "hear" each other just as if each handle referred to a channel of its own. If you open, say, channel 0 from thread A and thread B and then send a message from thread A, it will be "received" by thread B. This behaviour can be changed using canIOCTL_SET_LOCAL_TXECHO.

It is allowed to pass `NULL` as the value of msg, dlc, flag, and time.

Note
  Use canReadSpecific only if you for some reason must keep the unread messages in the queue. If this is not the case, consider using canReadSpecificSkip() or canRead() for better performance.

Parameters

  [in] | hnd | A handle to an open circuit.
  [in] | id | The desired CAN identifier.
  [out] | msg | Pointer to the buffer which receives the message data. This buffer must be large enough (i.e. 8 bytes for classic CAN and up to 64 bytes for CAN FD).
  [out] | dlc | Pointer to a buffer which receives the message length.
  [out] | flag | Pointer to a buffer which receives the message flags, which is a combination of the canMSG_xxx (including canFDMSG_xxx if the CAN FD protocol is enabled) and canMSGERR_xxx values.
  [out] | time | Pointer to a buffer which receives the message time stamp.

Returns
  canOK (zero) if a message was read.
  canERR_NOMSG (negative) if a matching message was not found. There might be other messages in the queue, though.
  canERR_xxx (negative) if failure

See also
  Message Mailboxes, Reading Messages, Time Stamping Accuracy and Resolution
  canRead(), canReadSpecificSkip(), canReadSync(), canReadSyncSpecific(), canReadWait()

## ◆ canReadSpecificSkip()

canStatus canReadSpecificSkip | ( | const CanHandle | hnd,
|  | long | id,
|  | void * | msg,
|  | unsigned int * | dlc,
|  | unsigned int * | flag,
|  | unsigned long * | time
| ) |  |

Reads a message with a specified identifier from the receive buffer. Any preceding message not matching the specified identifier will be removed in the receive buffer. If no message with the specified identifier is available, the function returns immediately with an error code.

If you are using the same channel via multiple handles, note that the default behaviour is that the different handles will "hear" each other just as if each handle referred to a channel of its own. If you open, say, channel 0 from thread A and thread B and then send a message from thread A, it will be "received" by thread B. This behaviour can be changed using canIOCTL_SET_LOCAL_TXECHO.

It is allowed to pass `NULL` as the value of msg, dlc, flag, and time.

Parameters

  [in] | hnd | A handle to an open circuit.
  [in] | id | The desired CAN identifier.
  [out] | msg | Pointer to the buffer which receives the message data. This buffer must be large enough (i.e. 8 bytes for classic CAN and up to 64 bytes for CAN FD).
  [out] | dlc | Pointer to a buffer which receives the message length.
  [out] | flag | Pointer to a buffer which receives the message flags, which is a combination of the canMSG_xxx (including canFDMSG_xxx if the CAN FD protocol is enabled) and canMSGERR_xxx values.
  [out] | time | Pointer to a buffer which receives the message time stamp.

Returns
  canOK (zero) if a matching message was found.
  canERR_NOMSG if there was no matching message available. All other messages (if any!) were discarded.
  canERR_xxx (negative) if failure

See also
  Reading Messages, Time Stamping Accuracy and Resolution
  canRead(), canReadSpecific(), canReadSync(), canReadSyncSpecific(), canReadWait()

## ◆ canReadStatus()

canStatus canReadStatus | ( | const CanHandle | hnd,
|  | unsigned long *const | flags
| ) |  |

Returns the status for the specified circuit. flags points to a longword which receives a combination of the canSTAT_xxx flags.

Note
  canReadStatus() returns the latest known status of the specified circuit. If a status change happens precisely when canReadStatus() is called, it may not be reflected in the returned result.

Parameters

  [in] | hnd | A handle to an open circuit.
  [out] | flags | Pointer to a `DWORD` which receives the status flags; this is a combination of any of the canSTAT_xxx.

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

## ◆ canReadSync()

canStatus canReadSync | ( | const CanHandle | hnd,
|  | unsigned long | timeout
| ) |  |

Waits until the receive buffer contains at least one message or a timeout occurs.

If you are using the same channel via multiple handles, note that the default behaviour is that the different handles will "hear" each other just as if each handle referred to a channel of its own. If you open, say, channel 0 from thread A and thread B and then send a message from thread A, it will be "received" by thread B. This behaviour can be changed using canIOCTL_SET_LOCAL_TXECHO.

Parameters

  [in] | hnd | A handle to an open circuit.
  [in] | timeout | The timeout in milliseconds. 0xFFFFFFFF gives an infinite timeout.

Returns
  canOK (zero) if the queue contains the desired message.
  canERR_TIMEOUT (negative) if a timeout occurs before a message arrived.
  canERR_xxx (negative) if the call fails.

See also
  canRead(), canReadSpecific(), canReadSpecificSkip(), canReadSyncSpecific(), canReadWait()

## ◆ canReadSyncSpecific()

canStatus canReadSyncSpecific | ( | const CanHandle | hnd,
|  | long | id,
|  | unsigned long | timeout
| ) |  |

Waits until the receive queue contains a message with the specified id, or a timeout occurs..

If you are using the same channel via multiple handles, note that the default behaviour is that the different handles will "hear" each other just as if each handle referred to a channel of its own. If you open, say, channel 0 from thread A and thread B and then send a message from thread A, it will be "received" by thread B. This behaviour can be changed using canIOCTL_SET_LOCAL_TXECHO.

Parameters

  [in] | hnd | A handle to an open circuit.
  [in] | id | The desired message identifier.
  [in] | timeout | The timeout in milliseconds. 0xFFFFFFFF gives an infinite timeout.

Returns
  canOK (zero) if the queue contains the desired message.
  canERR_TIMEOUT (negative) if a timeout occurs before the specified message arrived.
  canERR_xxx (negative) if the call fails.

See also
  canRead(), canReadSpecific(), canReadSpecificSkip(), canReadSync(), canReadWait()

## ◆ canReadWait()

canStatus canReadWait | ( | const CanHandle | hnd,
|  | long * | id,
|  | void * | msg,
|  | unsigned int * | dlc,
|  | unsigned int * | flag,
|  | unsigned long * | time,
|  | unsigned long | timeout
| ) |  |

Reads a message from the receive buffer. If no message is available, the function waits until a message arrives or a timeout occurs.

If you are using the same channel via multiple handles, note that the default behaviour is that the different handles will "hear" each other just as if each handle referred to a channel of its own. If you open, say, channel 0 from thread A and thread B and then send a message from thread A, it will be "received" by thread B. This behaviour can be changed using canIOCTL_SET_LOCAL_TXECHO.

It is allowed to pass `NULL` as the value of id, msg, dlc, flag, and time.

Parameters

  [in] | hnd | A handle to an open circuit.
  [out] | id | Pointer to a buffer which receives the CAN identifier. This buffer will only get the identifier. To determine whether this identifier was standard (11-bit) or extended (29-bit), and/or whether it was remote or not, or if it was an error frame, examine the contents of the flag argument.
  [out] | msg | Pointer to the buffer which receives the message data. This buffer must be large enough (i.e. 8 bytes for classic CAN and up to 64 bytes for CAN FD).
  [out] | dlc | Pointer to a buffer which receives the message length.
  [out] | flag | Pointer to a buffer which receives the message flags, which is a combination of the canMSG_xxx (including canFDMSG_xxx if the CAN FD protocol is enabled) and canMSGERR_xxx values.
  [out] | time | Pointer to a buffer which receives the message time stamp.
  [in] | timeout | If no message is immediately available, this parameter gives the number of milliseconds to wait for a message before returning. 0xFFFFFFFF gives an infinite timeout.

Returns
  canOK (zero) if a message was read.
  canERR_NOMSG (negative) if there was no message available.
  canERR_xxx (negative) if failure

See also
  canRead(), canReadSpecific(), canReadSpecificSkip(), canReadSyncSpecific(), canReadSync()
  Time Stamping Accuracy and Resolution

Examples:
  cancount.c, canfdmonitor.c, and canmonitor.c.

## ◆ canRequestBusStatistics()

canStatus canRequestBusStatistics | ( | const CanHandle | hnd | ) |

The canRequestBusStatistics function requests bus statistics from the hardware. The bus statistics figures can be retrieved later by a call to the canGetBusStatistics function.

Note
  The time between a call to canRequestBusStatistics() and the point in time where the bus statistics is actually available via a call to canGetBusStatistics() is not defined. Typically, you would call canRequestBusStatistics() from your application periodically (for example, once per second) to request the data from the driver and then call canGetBusStatistics() with the same rate to obtain the latest reported data.

Parameters

  [in] | hnd | An open handle to a CAN channel.

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

See also
  canGetBusStatistics()

## ◆ canRequestChipStatus()

canStatus canRequestChipStatus | ( | const CanHandle | hnd | ) |

This function is a dummy implementation for code portability. The Linux implementation of canReadStatus() will return the latest status without need of an additional call to canRequestChipStatus(), unlike the Windows counterpart.

Parameters

  [in] | hnd | An open handle to a CAN channel.

Returns
  canOK (zero)

See also
  canReadStatus()

## ◆ canResetBus()

canStatus canResetBus | ( | const CanHandle | hnd | ) |

This function tries to reset a CAN bus controller by taking the channel off bus and then on bus again (if it was on bus before the call to canResetBus().)

This function will affect the hardware (and cause a real reset of the CAN chip) only if hnd is the only handle open on the channel. If there are other open handles, this operation will not affect the hardware.

Parameters

  [in] | hnd | A handle to an open circuit.

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

See also
  canBusOn(), canBusOff()

## ◆ canSetAcceptanceFilter()

canStatus canSetAcceptanceFilter | ( | const CanHandle | hnd,
|  | unsigned int | code,
|  | unsigned int | mask,
|  | int | is_extended
| ) |  |

This routine sets the message acceptance filters on a CAN channel.

Format of code and mask:

- A binary 1 in a mask means "the corresponding bit in the code is relevant"
- A binary 0 in a mask means "the corresponding bit in the code is not relevant"
- A relevant binary 1 in a code means "the corresponding bit in the identifier must be 1"
- A relevant binary 1 in a code means "the corresponding bit in the identifier must be 1"

In other words, the message is accepted if ((code XOR id) AND mask) == 0.

extended should be set to:

- `0` (FALSE): if the code and mask shall apply to 11-bit CAN identifiers.
- `1` (TRUE): if the code and mask shall apply to 29-bit CAN identifiers.

If you want to remove a filter, call canSetAcceptanceFilter() with the mask set to `0`.

On some boards the acceptance filtering is done by the CAN hardware; on other boards (typically those with an embedded CPU,) the acceptance filtering is done by software. canSetAcceptanceFilter() behaves in the same way for all boards, however.

canSetAcceptanceFilter() and canAccept() both serve the same purpose but the former can set the code and mask in just one call.

Note
  You can set the extended code and mask only on CAN boards that support extended identifiers.
  Not all CAN boards support different masks for standard and extended CAN identifiers.
  Not implemented in linux.

Parameters

  [in] | hnd | An open handle to a CAN circuit.
  [in] | code | The acceptance code to set.
  [in] | mask | The acceptance mask to set.
  [in] | is_extended | Select 29-bit CAN identifiers.

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

See also
  canAccept / canSetAcceptanceFilter Example, Code and Mask Format
  canAccept()

## ◆ canSetBusOutputControl()

canStatus canSetBusOutputControl | ( | const CanHandle | hnd,
|  | const unsigned int | drivertype
| ) |  |

This function sets the driver type for a CAN controller. This corresponds loosely to the bus output control register in the CAN controller, hence the name of this function. CANlib does not allow for direct manipulation of the bus output control register; instead, symbolic constants are used to select the desired driver type.

Note
  Not all CAN driver types are supported on all cards.

Parameters

  [in] | hnd | A handle to an open circuit.
  [in] | drivertype | Can driver type, canDRIVER_xxx)

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

See also
  canGetBusOutputControl()

## ◆ canSetBusParams()

canStatus canSetBusParams | ( | const CanHandle | hnd,
|  | long | freq,
|  | unsigned int | tseg1,
|  | unsigned int | tseg2,
|  | unsigned int | sjw,
|  | unsigned int | noSamp,
|  | unsigned int | syncmode
| ) |  |

This function sets the nominal bus timing parameters for the specified CAN controller.

The library provides default values for tseg1, tseg2, sjw and noSamp when freq is specified to one of the pre-defined constants, canBITRATE_xxx for classic CAN and canFD_BITRATE_xxx for CAN FD.

If freq is any other value, no default values are supplied by the library.

If you are using multiple handles to the same physical channel, for example if you are writing a threaded application, you must call canBusOff() once for each handle. The same applies to canBusOn() - the physical channel will not go off bus until the last handle to the channel goes off bus.

Note
  Use canSetBusParamsC200() to set the bus timing parameters in the ubiquitous 82c200 bit-timing register format.

Parameters

  [in] | hnd | An open handle to a CAN controller.
  [in] | freq | Bit rate (measured in bits per second); or one of the predefined constants (canBITRATE_xxx for classic CAN and canFD_BITRATE_xxx for CAN FD).
  [in] | tseg1 | Time segment 1, that is, the number of quanta from (but not including) the Sync Segment to the sampling point.
  [in] | tseg2 | Time segment 2, that is, the number of quanta from the sampling point to the end of the bit.
  [in] | sjw | The Synchronization Jump Width.
  [in] | noSamp | The number of sampling points; can be 1 or 3.
  [in] | syncmode | Unsupported and ignored.

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

See also
  Bit Rate Examples, Bit Rate Constants, Bit Rate and Other Bus Parameters, canSetBusParams Example
  canSetBusParamsC200(), canGetBusParams()

Examples:
  busparms.c, cancount.c, canfdmonitor.c, canfdwrite.c, canmonitor.c, simplewrite.c, and writeloop.c.

## ◆ canSetBusParamsC200()

canStatus canSetBusParamsC200 | ( | const CanHandle | hnd,
|  | unsigned char | btr0,
|  | unsigned char | btr1
| ) |  |

This function sets the bus timing parameters using the same convention as the 82c200 CAN controller (which is the same as many other CAN controllers, for example, the 82527.)

To calculate the bit timing parameters, you can use the bit timing calculator that is included with CANlib SDK. Look in the BIN directory.

82c200 Bit Timing

- btr0 [b7..b6]: SJW - 1
- btr0 [b5..b0]: Prescaler -1
- btr1 [b7]: `1`: 3 samples, `0`: 1 samples
- btr1 [b6..b4]: tseg2 - 1
- btr1 [b3..b0]: tseg1 - 2

Note
  CANlib will always behave as if the clock frequency is 16 MHz. It does not matter if the device has a different physical clock, since this will be compensated for by the driver.

Parameters

  [in] | hnd | A handle to an open CAN circuit.
  [in] | btr0 | The desired bit timing, formatted as the contents of the BTR0 register in the 82c200.
  [in] | btr1 | The desired bit timing, formatted as the contents of the BTR1 register in the 82c200.

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

See also
  Bit Rate Examples, Bit Rate Constants
  canSetBusParams()

## ◆ canSetBusParamsFd()

canStatus canSetBusParamsFd | ( | const CanHandle | hnd,
|  | long | freq_brs,
|  | unsigned int | tseg1_brs,
|  | unsigned int | tseg2_brs,
|  | unsigned int | sjw_brs
| ) |  |

This function sets the data phase bus timing parameters for the specified CAN controller.

The library provides default values for tseg1_brs, tseg2_brs and sjw_brs when freq_brs is specified to one of the pre-defined constants, canFD_BITRATE_xxx.

If freq_brs is any other value, no default values are supplied by the library.

Parameters

  [in] | hnd | An open handle to a CAN controller.
  [in] | freq_brs | CAN FD data bit rate (measured in bits per second); or one of the predefined constants canFD_BITRATE_xxx.
  [in] | tseg1_brs | Time segment 1, that is, the number of quanta from (but not including) the Sync Segment to the sampling point.
  [in] | tseg2_brs | Time segment 2, that is, the number of quanta from the sampling point to the end of the bit.
  [in] | sjw_brs | The Synchronization Jump Width.

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

Examples:
  canfdmonitor.c, and canfdwrite.c.

## ◆ canSetDriverMode()

canStatus canSetDriverMode | ( | const CanHandle | hnd,
|  | int | lineMode,
|  | int | resNet
| ) |  |

This function sets the current CAN bus driver mode. This is typically a mode like sleep, wakeup, standby, fast mode, etc. The different modes are almost always hardware dependent and requires special DRVcan cables. As an example, the DRVcan S implements J2411 compliant single-wire CAN and supports four line modes, namely Normal, Sleep, Fast and Wakeup.

Standard ISO 11898 CAN do not support any of these bus driver modes.

Note
  The bus driver mode is typically used to control things like one- or two-wire mode, sleep mode, and so on. It requires special support in the CAN driver circuit.

Parameters

  [in] | hnd | An open handle to a CAN circuit.
  [in] | lineMode | An int which defines the line mode, canTRANSCEIVER_LINEMODE_xxx.
  [in] | resNet | An int which defines the resnet mode. Set this parameter to canTRANSCEIVER_RESNET_NA unless you have good reasons to set it to something else.

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

See also
  canGetDriverMode()

Note
  Not implemented in linux.

## ◆ canSetNotify()

canStatus canSetNotify | ( | const CanHandle | hnd,
|  | void(*)(canNotifyData *) | callback,
|  | unsigned int | notifyFlags,
|  | void * | tag
| ) |  |

This function associates a callback function with the CAN circuit.

Parameters

  [in] | hnd | A handle to an open CAN circuit.
  [in] | callback | Handle to callback routine.
  [in] | notifyFlags | The events specified with canNOTIFY_xxx, for which callback should be called.
  [in] | tag | Pointer to user defined data. Passed to callback in the canNotifyData struct.

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

Examples:
  canmonitor.c, and simplewrite.c.

## ◆ canTranslateBaud()

canStatus canTranslateBaud | ( | long *const | freq,
|  | unsigned int *const | tseg1,
|  | unsigned int *const | tseg2,
|  | unsigned int *const | sjw,
|  | unsigned int *const | nosamp,
|  | unsigned int *const | syncMode
| ) |  |

This function translates the canBITRATE_xxx constants to their corresponding bus parameter values. At return, this freq contains the actual bit rate (in bits per second). TSeg1 is the number of quanta (less one) in a bit before the sampling point. TSeg2 is the number of quanta after the sampling point.

Parameters

  [in,out] | freq | A pointer to a `DWORD` which contains the canBITRATE_xxx constant to translate. The bitrate constant value is overwritten with the frequency value.
  [out] | tseg1 | A pointer to a buffer which receives the Time segment 1, that is, the number of quanta from (but not including) the Sync Segment to the sampling point.
  [out] | tseg2 | A pointer to a buffer which receives the Time segment 2, that is, the number of quanta from the sampling point to the end of the bit.
  [out] | sjw | A pointer to a buffer which receives the Synchronization Jump Width.
  [out] | nosamp | A pointer to a buffer which receives the number of sampling points.
  [out] | syncMode | Unsupported, always read as zero. May be set to NULL.

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

See also
  canSetBusParams()

## ◆ canWrite()

canStatus canWrite | ( | const CanHandle | hnd,
|  | long | id,
|  | void * | msg,
|  | unsigned int | dlc,
|  | unsigned int | flag
| ) |  |

This function sends a CAN message. The call returns immediately after queuing the message to the driver.

If you are using the same channel via multiple handles, note that the default behaviour is that the different handles will "hear" each other just as if each handle referred to a channel of its own. If you open, say, channel 0 from thread A and thread B and then send a message from thread A, it will be "received" by thread B. This behaviour can be changed using canIOCTL_SET_LOCAL_TXECHO.

Note
  The message has been queued for transmission when this calls return. It has not necessarily been sent.

Parameters

  [in] | hnd | A handle to an open CAN circuit.
  [in] | id | The identifier of the CAN message to send.
  [in] | msg | A pointer to the message data, or `NULL`.
  [in] | dlc | The length of the message in bytes. For Classic CAN dlc can be at most 8, unless canOPEN_ACCEPT_LARGE_DLC is used. For CAN FD dlc can be one of the following 0-8, 12, 16, 20, 24, 32, 48, 64.
  [in] | flag | A combination of message flags, canMSG_xxx (including canFDMSG_xxx if the CAN FD protocol is enabled). Use this parameter to send extended (29-bit) frames and/or remote frames. Use canMSG_EXT and/or canMSG_RTR for this purpose.

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

See also
  Sending Messages, canWrite Example
  canWriteSync(), canWriteWait()

Examples:
  canfdwrite.c, and simplewrite.c.

## ◆ canWriteSync()

canStatus canWriteSync | ( | const CanHandle | hnd,
|  | unsigned long | timeout
| ) |  |

Waits until all CAN messages for the specified handle are sent, or the timeout period expires.

Parameters

  [in] | hnd | A handle to an open CAN circuit.
  [in] | timeout | The timeout in milliseconds. 0xFFFFFFFF gives an infinite timeout.

Returns
  canOK (zero) if the queue emptied before the timeout period came to its end.
  canERR_TIMEOUT (negative) not all messages were transmitted when the timeout occurred.
  canERR_PARAM (negative) This could be caused by an erroneous parameter, or if you have turned TXACKs off (by using canIoCtl()) because if you do you can't use this call. The driver simply doesn't know when all the messages are sent!
  canERR_xxx (negative) if failure

See also
  canWrite(), canWriteWait()

Examples:
  canfdwrite.c, and simplewrite.c.

## ◆ canWriteWait()

canStatus canWriteWait | ( | const CanHandle | hnd,
|  | long | id,
|  | void * | msg,
|  | unsigned int | dlc,
|  | unsigned int | flag,
|  | unsigned long | timeout
| ) |  |

This function sends a CAN message. It returns when the message is sent, or the timeout expires.

This is a convenience function that combines canWrite() and canWriteSync().

If you are using the same channel via multiple handles, note that the default behaviour is that the different handles will "hear" each other just as if each handle referred to a channel of its own. If you open, say, channel 0 from thread A and thread B and then send a message from thread A, it will be "received" by thread B. This behaviour can be changed using canIOCTL_SET_LOCAL_TXECHO.

Parameters

  [in] | hnd | A handle to an open CAN circuit.
  [in] | id | The identifier of the CAN message to send.
  [in] | msg | A pointer to the message data, or `NULL`.
  [in] | dlc | The length of the message in bytes. For Classic CAN dlc can be at most 8, unless canOPEN_ACCEPT_LARGE_DLC is used. For CAN FD dlc can be one of the following 0-8, 12, 16, 20, 24, 32, 48, 64.
  [in] | flag | A combination of message flags, canMSG_xxx. Use this parameter to send extended (29-bit) frames and/or remote frames. Use canMSG_EXT and/or canMSG_RTR for this purpose.
  [in] | timeout | The timeout, in milliseconds. 0xFFFFFFFF gives an infinite timeout.

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

Examples:
  writeloop.c.