Overview

Error and event handling This group defines all required functions for handling of common bus events and errors.

Collaboration diagram for Error and Event Handling:

Enumerations
enum	LCB_EventId { LCB_EVENT_DATA_LINK_LAYER = 2, LCB_EVENT_ERR = 4, LCB_EVENT_DEVICE_EMERGENCY = 5, LCB_EVENT_DEVICE_GUARD = 6 }
	Event identifier returned in EventId when reading event queue via LCB_ReadEventEx(). More...

enum	LCB_GuardEventId { NODEGUARD_ERR_OCCURED = 0, NODEGUARD_ERR_RESOLVED, HEARTBEAT_ERR_OCCURED, HEARTBEAT_ERR_RESOLVED, NODESTATE_ERR, NODESTATE_CHANGED }
	Guard event identifier that is returned in the first data field if the event type is LCB_EVENT_DEVICE_GUARD. More...

Functions
long	LCB_GetErrMsg (long ErrCode, char *pMsgBuf, int MsgBufSize)
	Get descriptive error message for a certain error return code. More...

long	LCB_GetExtendedLastErrorString (char *pStringBuf, int StringBufSize)
	If an error occurs, then a function returns an error code. More...

long	LCB_ReadEvent (long pEventId, long pData1, long pData2, long pData3)
	Try to read one event from the lab event queue. More...

long	LCB_ReadEventEx (long pEventId, dev_hdl pDeviceHandle, long pData1, long pData2, char *pEventString, int EventStringSize)
	Try to read one event from the lab event queue. More...

Enumeration Type Documentation

enum LCB_EventId

Event identifier returned in EventId when reading event queue via LCB_ReadEventEx().

Enumerator
LCB_EVENT_DATA_LINK_LAYER	Data link layer event. These are events that occur in the data link layer - e.g. if the interface is disconnected or if the data transfer fails for some reason. The data that is returned if the first data field of LCB_ReadEventEx() contains the error code or the error that occurred. You can pass this error to LCB_GetErrMsg() to get a human readable error message. This event returns the following data: pData1 - Data link layer error code
LCB_EVENT_ERR	Error event - an error occurred. You can pass this error to LCB_GetErrMsg() to get a human readable error message. This event returns the following data: pData1 - Emergency error code
LCB_EVENT_DEVICE_EMERGENCY	Device specific emergency event. Identifies device specific emergency messages. Devices use emergency events to indicate failures and unexpected events. This event returns the following data: pDeviceHandle - Device handle of device that caused the emergency event pData1 - Emergency error code You can use the device handle for functions that required a device handle. You can call LCB_GetDevErrMsg() with the device handle and the emergency error code as parameter to get a descriptive error message string for the emergency error returned in pData1
LCB_EVENT_DEVICE_GUARD	A guarding event (nodeguard or heartbeat) occurred. This event returns the following data: pDeviceHandle - Device handle of device that caused guard event pData1 - Guard event id LCB_GuardEventId

enum LCB_GuardEventId

Guard event identifier that is returned in the first data field if the event type is LCB_EVENT_DEVICE_GUARD.

Devices can be monitored by the means of the Node Guarding Protocol or the Heartbeat Protocol. See https://www.can-cia.org/can-knowledge/canopen/error-control-protocols/ for details. If a guarding error occurs, this is identified by this ID.

Enumerator
NODEGUARD_ERR_OCCURED	node guard error occurred - device did not respond
NODEGUARD_ERR_RESOLVED	node guard error resolved
HEARTBEAT_ERR_OCCURED	heartbeat error occurred
HEARTBEAT_ERR_RESOLVED	heartbeat error resolved
NODESTATE_ERR	node state error
NODESTATE_CHANGED	node state changed

Function Documentation

long LCB_GetErrMsg	(	long	ErrCode,
		char *	pMsgBuf,
		int	MsgBufSize
	)

Get descriptive error message for a certain error return code.

Parameters

[in]	ErrCode	Error code of device error that occurred
[out]	pMsgBuf	Message buffer for storage of error message string
[in]	MsgBufSize	Size of message buffer pMsgBuf in bytes

Returns: Error code - ERR_NOERR indicates success

Examples:: capi_event_queue_test.cpp.

long LCB_GetExtendedLastErrorString	(	char *	pStringBuf,
		int	StringBufSize
	)

If an error occurs, then a function returns an error code.

This error code can be converted into an error message. For many errors additional extended error information is stored internally. So in case a function returns an error, you can call this function Immediately to get optional extended error information.

Parameters

[out]	pStringBuf	Message buffer for storage of error message string
[in]	StringBufSize	Size of message buffer pMsgBuf in bytes

Returns: Error code - ERR_NOERR indicates success

Examples:: capi_nemesys4_test.cpp.

Referenced by capiErrorString().

long LCB_ReadEvent	(	long *	pEventId,
		long *	pData1,
		long *	pData2,
		long *	pData3
	)

Try to read one event from the lab event queue.

The internal queue stores events like network events, emergency events of single devices. This function tries to read one event from this queue and returns immediately with -ERR_AGAIN if no event is in queue.

Parameters

[out]	pEventId	Stores the event identifier read from queue
[out]	pData1	Stores the event specific data 1
[out]	pData2	Stores the event specific data 2
[out]	pData3	Stores the event specific data 3

Return values

ERR_NOERR	A event has been read successfully from queue
ERR_AGAIN	The queue is empty - try again later
ERR_PARAM_INVALID	The bus handle in hBus is not valid or initialized

See also: lcb_event_id

Deprecated:: This function is deprecated. Use LCB_ReadEventEx() for future implementations

long LCB_ReadEventEx	(	long *	pEventId,
		dev_hdl *	pDeviceHandle,
		long *	pData1,
		long *	pData2,
		char *	pEventString,
		int	EventStringSize
	)

Try to read one event from the lab event queue.

The internal queue stores events like network events, emergency events, data link layer events or events of single devices. This function tries to read one event from this queue and returns immediately with -ERR_AGAIN if no event is in queue.

Parameters

[out]	pEventId	Stores the event identifier read from queue. See LCB_EventId for a detailed description of the event identifiers.
[out]	pDeviceHandle	Returns a device handle for certain event types
[out]	pData1	Stores the event specific data 1
[out]	pData2	Stores the event specific data 2
[out]	pEventString	Returns a descriptive string of the event and its parameters.
[in]	EventStringSize	Size of the message buffer for the returned string

Return values

ERR_NOERR	A event has been read successfully from queue
ERR_AGAIN	The queue is empty - try again later
ERR_PARAM_INVALID	The bus handle in hBus is not valid or initialized

See also: LCB_EventId and LCB_GuardEventId

Examples:: capi_event_queue_test.cpp.

Overview

Enumerations

Functions

Enumeration Type Documentation

Function Documentation