c header file for socan object layer library. More...

#include <stdbool.h>

Macros
#define	SOCAN_VERSION_STR "1.2.1"

#define	SOCAN_VERSION_MAJOR 1

#define	SOCAN_VERSION_MINOR 2

#define	SOCAN_MAX_PORTS 8

#define	SOCAN_FRAME_LENGTH 8

#define	COB_NO 2048

Typedefs
typedef struct socan_obj_s *	socan_obj_h

typedef struct socan_hdl_s *	socan_hdl

Enumerations
enum	socan_obj_type { SOCAN_READ , SOCAN_WRITE , SOCAN_READ_RTR , SOCAN_WRITE_RTR }

enum	socan_rc { SOCAN_OK = 0 , SOCAN_TIMEOUT = 1 , SOCAN_OLD = 2 , SOCAN_LOST = 3 , SOCAN_WAIT = 4 , SOCAN_EXISTS = 5 , SOCAN_LENGTH_ERR = 6 , SOCAN_PORT_ERR = 7 , SOCAN_COB_ERR = 8 , SOCAN_NOT_RO_ERR = 9 , SOCAN_NOT_WO_ERR =10 , SOCAN_TYPE_ERR =11 , SOCAN_NOT_EXISTS_ERR =12 , SOCAN_NOT_OWNED_ERR =13 , SOCAN_EXISTS_ERR =14 , SOCAN_ERROR =15 }

Functions
char *	socan_str_rc (socan_rc rc)

bool	socan_rc_is_error (socan_rc rc)

int	socan_errprintlevel (int level)

int	socan_tracelevel (int level)

int	socan_add_port (const char *devicename)

bool	socan_realtime_setup (bool use_rt_priority, bool require_rt_priority, int reader_priority, int writer_priority)

bool	socan_init (void)

socan_rc	socan_port_bitrate (unsigned char port, unsigned int *bitrate)

socan_hdl	socan_open (void)

bool	socan_close (socan_hdl h)

socan_rc	socan_port_device (unsigned char port, char **dev)

socan_rc	socan_add_obj (socan_hdl hdl, unsigned char port, unsigned short cob, unsigned char length, unsigned int tmo_ms, socan_obj_type type)

socan_rc	socan_del_obj (unsigned char port, unsigned short cob)

socan_rc	socan_obj_info (socan_hdl hdl, unsigned char port, unsigned short cob, unsigned char length, unsigned int tmo_ms, socan_obj_type *type)

socan_rc	socan_obj_ts (unsigned char port, unsigned short cob, unsigned long *ts)

socan_rc	socan_ts_to_str (unsigned long ts, char *buf, int buflen)

socan_rc	socan_set_inhibit (unsigned char port, unsigned short cob, unsigned long inhibit_time)

socan_rc	socan_use_queue (unsigned char port, unsigned short cob)

socan_rc	socan_new_user_area (unsigned char port, unsigned short cob, unsigned int size, void **area)

socan_rc	socan_user_area (unsigned char port, unsigned short cob, void **area)

socan_rc	socan_set_user_area (unsigned char port, unsigned short cob, void *ptr)

socan_rc	socan_free_user_area (unsigned char port, unsigned short cob)

socan_rc	socan_write (socan_hdl hdl, unsigned char port, unsigned short cob, const void *data)

socan_rc	socan_writelater (socan_hdl hdl, unsigned char port, unsigned short cob, const void *data)

socan_rc	socan_write_inhibit (socan_hdl hdl, unsigned char port, unsigned short cob, const void data, unsigned long inhibit_time)

socan_rc	socan_readnow (socan_hdl hdl, unsigned char port, unsigned short cob, void *data)

socan_rc	socan_read (socan_hdl hdl, unsigned char port, unsigned short cob, void *data)

socan_rc	socan_queue_read (socan_hdl hdl, unsigned char port, unsigned short cob, void *data)

Detailed Description

c header file for socan object layer library.

This header, socan.h, contains all data types and functions of the socan object layer library.

Main features are:

The object layer library of socan implements CAN object data types and functions for the Linux SocketCAN interface. The CAN object abstraction allows the definition of CAN objects with a type, read, write, remote-read, remote-write, and a length, 0 to 8 bytes.
Internal reader threads of the library ensure that incoming CAN data is stored buffers, one for each CAN object, together with a time stamp.
The library only accepts data from CAN objects that were previously defined.
Internal writer threads allow the application to write CAN data frames asynchronously. When the data is actually written to the CAN bus, the library stores a write time stamp with the CAN object.
The reader and writer threads implement an automatic answer of incoming remote (RTR) CAN frames.
The library keeps track of when incoming data was read or not. The application is informed by a flag, when it has lost CAN data. This happens when two or more CAN frames arrived for the CAN object since the last read operation on the CAN object.
The library allows the definition of an inhibit time which prevents it from sending out CAN objects too fast for a receiver.
The library can be used by more than one thread at once.
CAN interfaces are distinguished by a number, a so called port. The library provides a function to associate port numbers with SocketCAN devices.
A User defined data block can be associated with each CAN object, the application doesn't need to implement a mapping from port and cob to a data structure.
The library supports reading of a specific CAN object or waiting for incoming data on an arbitrary number of CAN objects.

Definition in file socan.h.

Macro Definition Documentation

◆ COB_NO

#define COB_NO 2048

Maximum number of CAN object IDs.

This is is fixed number in the original CAN bus standard. Note that socan allocates a lookup table with a size of sizeof(void*) * COB_NO * SOCAN_MAX_PORTS bytes to map CAN object IDs to the data structure of a CAN object.

Definition at line 146 of file socan.h.

◆ SOCAN_FRAME_LENGTH

#define SOCAN_FRAME_LENGTH 8

Maximum length of a CAN frame in bytes.

For now, socan only supports CAN frames with a maximum length of 8 bytes, you cannot change this constant.

Definition at line 137 of file socan.h.

◆ SOCAN_MAX_PORTS

#define SOCAN_MAX_PORTS 8

The maximum number of supported CAN ports.

Since the data type for a CAN port is unsigned char, this constant must never be greater than 255.

This constant means that the socan library can handle no more than SOCAN_MAX_PORTS CAN devices at a time. It means that you can only map up to this number SocketCAN interfaces to port numbers.

You may increase this constant and recompile the library if needed. This constant determines at some places in the code how much memory is allocated.

Definition at line 130 of file socan.h.

◆ SOCAN_VERSION_MAJOR

#define SOCAN_VERSION_MAJOR 1

The major version number of SOCAN as an integer

Definition at line 112 of file socan.h.

◆ SOCAN_VERSION_MINOR

#define SOCAN_VERSION_MINOR 2

The minor version number of SOCAN as an integer

Definition at line 115 of file socan.h.

◆ SOCAN_VERSION_STR

#define SOCAN_VERSION_STR "1.2.1"

The version of SOCAN as a string

Definition at line 109 of file socan.h.

Typedef Documentation

◆ socan_hdl

typedef struct socan_hdl_s* socan_hdl

Abstract data type for socan handle.

This data type has a function similar to FILE for some of the standard I/O functions in c. The handle is used by the socan object layer library to distinguish between different threads that may use the library concurrently.

Definition at line 211 of file socan.h.

◆ socan_obj_h

typedef struct socan_obj_s* socan_obj_h

Abstract data type for a CAN object

Definition at line 203 of file socan.h.

Enumeration Type Documentation

◆ socan_obj_type

enum socan_obj_type

Type of a CAN object.

There are four possible types of a CAN object

read: you can only read from this CAN object
write: you can only write to this CAN object
remote read: a read sends an RTR CAN frame and waits for a reply
remote write: a write changes the local CAN buffer only, incoming RTR CAN frame are answered automatically

Enumerator
SOCAN_READ	read CAN object
SOCAN_WRITE	write CAN object
SOCAN_READ_RTR	remote-read CAN object
SOCAN_WRITE_RTR	remote-write CAN object

Definition at line 161 of file socan.h.

◆ socan_rc

enum socan_rc

Return codes for functions.

All functions of socan return this type. Some of the values are flags, some are errors. Function socan_rc_is_error() can be used to distinguish between flags and errors.

Enumerator
SOCAN_OK	no error
SOCAN_TIMEOUT	timeout
SOCAN_OLD	data in CAN buffer is old (was already read)
SOCAN_LOST	some CAN data was not read (reading was too slow)
SOCAN_WAIT	writing cannot be done (inhibit time not yet passed)
SOCAN_EXISTS	CAN object already defined
SOCAN_LENGTH_ERR	wrong length of incoming data
SOCAN_PORT_ERR	invalid port number
SOCAN_COB_ERR	invalid CAN object id
SOCAN_NOT_RO_ERR	CAN object is not SOCAN_READ
SOCAN_NOT_WO_ERR	CAN object is not SOCAN_WRITE
SOCAN_TYPE_ERR	CAN object has wrong type
SOCAN_NOT_EXISTS_ERR	CAN object is not defined (for given CAN object id)
SOCAN_NOT_OWNED_ERR	CAN object is not owner by this thread
SOCAN_EXISTS_ERR	CAN object already exists but with different parameters
SOCAN_ERROR	generic CAN error

Definition at line 175 of file socan.h.

Function Documentation

◆ socan_add_obj()

socan_rc socan_add_obj	(	socan_hdl	hdl,
		unsigned char	port,
		unsigned short	cob,
		unsigned char	length,
		unsigned int	tmo_ms,
		socan_obj_type	type )

extern

Define a CAN object.

Before reading from or writing to a CAN object, it has to be defined with this function.

Parameters

[in]	hdl	The handle obtained by socan_open().
[in]	port	The number of the CAN port
[in]	cob	The CAN object ID.
[in]	length	The length of the CAN object in bytes. The minimum value is 0, the maximum value is SOCAN_FRAME_LENGTH.
[in]	tmo_ms	The timeout in milliseconds.
[in]	type	The type of the CAN object

Returns

A socan_rc return code, possible other values are:

SOCAN_OK : Defining the CAN object was successful.
SOCAN_EXISTS : The CAN object already exists
SOCAN_EXISTS_ERR : The CAN object already exists but with different properties.
SOCAN_NOT_OWNED_ERR : The CAN object already exists but was defined by a different thread (using a different handle 'hdl').
SOCAN_PORT_ERR : The port number is invalid
SOCAN_COB_ERR : The CAN object ID is invalid
SOCAN_LENGTH_ERR : The length is invalid.

Definition at line 1459 of file socan.c.

◆ socan_add_port()

int socan_add_port ( const char * devicename )

extern

Add a SocketCAN device as a new CAN port.

socan used CAN ports to distinguish physical CAN interfaces. This functions associates a new CAN port number with the given interface name.

Parameters

[in] devicename The name of the CAN device. You can see can devices with the command 'ip link'.

Returns: The port number that was assigned to the device or -1 in case of an error.

Definition at line 1395 of file socan.c.

◆ socan_close()

bool socan_close ( socan_hdl h )

extern

Close the library for an application.

Closes the library and frees all resources that were occupied by the application program.

Returns: true on success, false in case of an error.

Definition at line 1196 of file socan.c.

◆ socan_del_obj()

socan_rc socan_del_obj	(	unsigned char	port,
		unsigned short	cob )

extern

Delete a CAN object and free it's resources.

This deletes a CAN object that was previously defined with socan_add_obj(). Note that it is not an error, when the CAN object wasn't defined in the first place. In this case, the function does nothing and returns SOCAN_OK.

Parameters

[in]	port	The port number.
[in]	cob	The CAN object id

Returns

A socan_rc return code, possible other values are:

SOCAN_OK : Defining the CAN object was successful.
SOCAN_PORT_ERR : The port number is invalid
SOCAN_COB_ERR : The CAN object ID is invalid

Definition at line 1502 of file socan.c.

◆ socan_errprintlevel()

int socan_errprintlevel ( int level )

extern

Get and/or set the socan error print level.

The error print level determines if and when messages are printed to the console in case of errors. These are the currently known error print levels:

0: no output
1: output of severe errors, system calls that failed
2: output of usage errors, invalid parameters
3: output of run-time errors (e.g. congestion)

Parameters

[in] level The error print level. If >=0, set this as new error print level. If <0, do not change the error print level, only read it.

Returns: The current or new error print level

Definition at line 288 of file socan.c.

◆ socan_free_user_area()

socan_rc socan_free_user_area	(	unsigned char	port,
		unsigned short	cob )

extern

Free a memory memory block associated with a CAN object.

This function calls free() on the memory block that was associated with a CAN object by calling socan_new_user_area() or socan_set_user_area(). If there is no associated memory block the function simply returns SOCAN_OK.

Parameters

[in]	port	The port number.
[in]	cob	The CAN object ID.

Returns

A socan_rc return code, possible other values are:

SOCAN_OK : Setting the inhibit time was successful.
SOCAN_PORT_ERR : The port number is invalid
SOCAN_COB_ERR : The CAN object ID is invalid
SOCAN_NOT_EXISTS_ERR : The CAN object doesn't exist.
SOCAN_NOT_OWNED_ERR : The CAN object exists but was defined by a different thread (using a different handle 'hdl').

Definition at line 1674 of file socan.c.

◆ socan_init()

bool socan_init ( void )

extern

Initialize the socan library.

This starts the internal data structures and starts the library threads. You should have added CAN bus ports with socan_add_port() before.

Returns: true when initialization was successful.

Definition at line 2538 of file socan.c.

◆ socan_new_user_area()

socan_rc socan_new_user_area	(	unsigned char	port,
		unsigned short	cob,
		unsigned int	size,
		void **	area )

extern

Create a memory block associated with a CAN object.

A memory block of arbitrary size is created with this function. This memory block is associated with the CAN object and can later be retrieved with function socan_user_area(). This can be used for the application to store additional data with a CAN object. Note that this function allocates new memory. If there was already a memory block associated, this block is freed first. When the CAN object is later deleted with socan_del_obj(), the memory block is freed, too.

Parameters

[in]	port	The port number.
[in]	cob	The CAN object ID.

Returns

A socan_rc return code, possible other values are:

SOCAN_OK : Setting the inhibit time was successful.
SOCAN_PORT_ERR : The port number is invalid
SOCAN_COB_ERR : The CAN object ID is invalid
SOCAN_NOT_EXISTS_ERR : The CAN object doesn't exist.
SOCAN_NOT_OWNED_ERR : The CAN object exists but was defined by a different thread (using a different handle 'hdl').

Definition at line 1621 of file socan.c.

◆ socan_obj_info()

socan_rc socan_obj_info	(	socan_hdl	hdl,
		unsigned char	port,
		unsigned short	cob,
		unsigned char *	length,
		unsigned int *	tmo_ms,
		socan_obj_type *	type )

extern

Return information for a CAN object.

This returns properties of the CAN object.

Parameters

[in]	hdl	The handle obtained by socan_open().
[in]	port	The port number.
[in]	cob	The CAN object id
[out]	length	This length is returned in this parameter
[out]	tmo_ms	This timeout is returned in this parameter
[out]	type	The type of the CAN object is returned in this parameter

Returns

A socan_rc return code, possible other values are:

SOCAN_OK : Defining the CAN object was successful.
SOCAN_PORT_ERR : The port number is invalid
SOCAN_COB_ERR : The CAN object ID is invalid
SOCAN_NOT_OWNED_ERR : The CAN object was defined by a different thread (using a different handle 'hdl').

Definition at line 1523 of file socan.c.

◆ socan_obj_ts()

socan_rc socan_obj_ts	(	unsigned char	port,
		unsigned short	cob,
		unsigned long *	ts )

extern

Return the time stamp of the CAN object.

For read objects, this is the time when data arrived for this object. For write objects this is the time when data was written to the CAN bus for this object. The time stamp is measured in microseconds. The absolute value of the time stamp is compatible with the function gettimeofday as provided by libc. You would get a compatible time stamp like this:

#include <sys/time.h>
struct timeval now;
unsigned long timestamp;
gettimeofday(&now, NULL);
timestamp= now->tv_sec * 1000 + now->tv_usec / 1000;

Parameters

[in]	port	The number of the CAN port
[in]	cob	The CAN object ID.
[out]	ts	The time stamp is returned here.

Returns

A socan_rc return code, possible other values are:

SOCAN_OK : Getting the time stamp was successful.
SOCAN_PORT_ERR : The port number is invalid
SOCAN_COB_ERR : The CAN object ID is invalid
SOCAN_NOT_EXISTS_ERR : The CAN object doesn't exist.
SOCAN_NOT_OWNED_ERR : The CAN object exists but was defined by a different thread (using a different handle 'hdl').

Definition at line 1549 of file socan.c.

◆ socan_open()

socan_hdl socan_open ( void )

extern

Open the library for an application.

This function returns a handle that must be used by the application for most calls to the library.

Returns: the handle or NULL in case of an error

Definition at line 1151 of file socan.c.

◆ socan_port_bitrate()

socan_rc socan_port_bitrate	(	unsigned char	port,
		unsigned int *	bitrate )

extern

Return the bit rate of a port.

This function returns the bit rate of a port in bits/sec. It calls 'ip -details link show DEVICE' to get the bit rate of a port.

Returns: the bit rate in bits/sec or -1 in case of an error.

Definition at line 1089 of file socan.c.

◆ socan_port_device()

socan_rc socan_port_device	(	unsigned char	port,
		char **	dev )

extern

Return the device name associated with a port.

This is the same device name that was given to socan_add_port() to associate the device name with a port previously.

Parameters

[in]	port	The port number.
[out]	dev	A pointer to a pointer of char. When the function returns, '*dev' will point to the device name.

Returns: A socan_rc return code, either SOCAN_OK or SOCAN_PORT_ERR when the given port number was invalid.

Definition at line 1233 of file socan.c.

◆ socan_queue_read()

socan_rc socan_queue_read	(	socan_hdl	hdl,
		unsigned char *	port,
		unsigned short *	cob,
		void *	data )

extern

Blocking read any of the queue-read CAN objects.

Queue-read CAN objects are CAN objects of type SOCAN_READ or SOCAN_READ_RTR which were configured with function socan_use_queue(). The function waits until new data is available on any of the queue read objects. Note that there is no timeout here, if no new data arrives, the function will wait indefinitely. For SOCAN_READ_RTR objects new data will only be received when you create an RTR-read request first. This is done by calling socan_write(), socan_writelater() or socan_write_inhibit() on the SOCAN_READ_RTR object.

Parameters

[in]	hdl	The handle obtained by socan_open().
[out]	port	The port number of the CAN object that was read.
	[cob]	cob The CAN object ID. of the CAN object that was read.
[out]	data	A pointer to the data.

Returns

A socan_rc return code, possible other values are:

SOCAN_OK : Setting the inhibit time was successful.
SOCAN_LENGTH_ERR : The length of the received data was wrong.
SOCAN_LOST : Data was lost, this means that since the last call of a read function for the CAN object, more than one new CAN frame has arrived. The returned data is the most recent one.

Definition at line 1867 of file socan.c.

◆ socan_rc_is_error()

bool socan_rc_is_error ( socan_rc rc )

extern

Show if a socan_rc return code represents an error.

Parameters

[in] rc The return code

Returns: true if rc is an error code.

Definition at line 395 of file socan.c.

◆ socan_read()

socan_rc socan_read	(	socan_hdl	hdl,
		unsigned char	port,
		unsigned short	cob,
		void *	data )

extern

Blocking read of a SOCAN_READ or SOCAN_READ_RTR object.

This function reads from a CAN object and waits until new data arrives. For remote read (SOCAN_READ_RTR) objects, the function sends an RTR frame and waits for the reply.

Parameters

[in]	hdl	The handle obtained by socan_open().
[in]	port	The port number.
[in]	cob	The CAN object ID.
[out]	data	A pointer to the data.

Returns

A socan_rc return code, possible other values are:

SOCAN_OK : Setting the inhibit time was successful.
SOCAN_PORT_ERR : The port number is invalid
SOCAN_COB_ERR : The CAN object ID is invalid
SOCAN_NOT_EXISTS_ERR : The CAN object doesn't exist.
SOCAN_NOT_OWNED_ERR : The CAN object exists but was defined by a different thread (using a different handle 'hdl').
SOCAN_NOT_RO_ERR : The CAN object is neither a SOCAN_READ nor a SOCAN_READ_RTR object.
SOCAN_TIMEOUT : The data couldn't be read within the timeout time.
SOCAN_OLD : The data is old, meaning that since the last call of a read function for this CAN object, no new data has arrived.
SOCAN_LENGTH_ERR : The length of the received data was wrong.
SOCAN_LOST : Data was lost, this means that since the last call of a read function for this CAN object, more than one new CAN frame has arrived. The returned data is the most recent one.

Definition at line 1758 of file socan.c.

◆ socan_readnow()

socan_rc socan_readnow	(	socan_hdl	hdl,
		unsigned char	port,
		unsigned short	cob,
		void *	data )

extern

Read buffer from a SOCAN_READ or SOCAN_READ_RTR object and return immediately.

This function reads the local data buffer of the CAN object. Note that for remote read (SOCAN_READ_RTR) objects, the function does not issue a RTR frame, no data is sent to the CAN bus. The function always returns immediately.

Parameters

[in]	hdl	The handle obtained by socan_open().
[in]	port	The port number.
[in]	cob	The CAN object ID.
[out]	data	A pointer to the data.

Returns

A socan_rc return code, possible other values are:

SOCAN_OK : Setting the inhibit time was successful.
SOCAN_PORT_ERR : The port number is invalid
SOCAN_COB_ERR : The CAN object ID is invalid
SOCAN_NOT_EXISTS_ERR : The CAN object doesn't exist.
SOCAN_NOT_OWNED_ERR : The CAN object exists but was defined by a different thread (using a different handle 'hdl').
SOCAN_NOT_RO_ERR : The CAN object is neither a SOCAN_READ nor a SOCAN_READ_RTR object.
SOCAN_OLD : The data is old, meaning that since the last call of a read function for this CAN object, no new data has arrived.
SOCAN_LENGTH_ERR : The length of the received data was wrong.
SOCAN_LOST : Data was lost, this means that since the last call of a read function for this CAN object, more than one new CAN frame has arrived. The returned data is the most recent one.

Definition at line 1698 of file socan.c.

◆ socan_realtime_setup()

bool socan_realtime_setup	(	bool	use_rt_priority,
		bool	require_rt_priority,
		int	reader_priority,
		int	writer_priority )

extern

Set up real time scheduling and priorities.

This function can be called before socan_init() is called. It is used to change the defaults for the real time priorities of the library. These are the defaults, if socan_realtime_setup is not called:

use_rt_priority: true
require_rt_priority: false
reader_priority: 97 (see READER_DEFAULT_PRIO in socan.c)
writer_priority: 97 (see WRITER_DEFAULT_PRIO in socan.c)

Parameters

[in]	use_rt_priority	If true, the library uses real time priorities for it's internal threads and SCHED_FIFO scheduling polity. If false, it uses SCHED_OTHER scheduling policy and default priorities. The reader_priority and writer_priority parameters are ignored in this case.
[in]	require_rt_priority	If true and if use_rt_priority is true, real time priorities are considered mandatory. If the application has no sufficient rights to use SCHED_FIFO scheduling policy and real time priorities, socan_init() will fail. If require_rt_priority is false, real time priorities are considered optional, insufficient rights do not cause socan_init() to fail, it only prints a warning and uses normal SCHED_OTHER policy and default priorities.
[in]	reader_priority	This is the priority of the internal reader task when real time priorities are used (see also use_rt_priority and require_rt_priority).
[in]	writer_priority	This is the priority of the internal writer task when real time priorities are used (see also use_rt_priority and require_rt_priority).

Returns: true on success and false on error.

Definition at line 2472 of file socan.c.

◆ socan_set_inhibit()

socan_rc socan_set_inhibit	(	unsigned char	port,
		unsigned short	cob,
		unsigned long	inhibit_time )

extern

Sets the inhibit time of a CAN object.

The inhibit time is the minimum time that between two write operations on the same CAN object. This is intended to avoid congestion (data loss) on the receiver. The inhibit time is observed by some of the write functions, see also the documentation of these functions.

Parameters

[in]	port	The port number.
[in]	cob	The CAN object ID.
[in]	inhibit_time	The inhibit time in microseconds

Returns

A socan_rc return code, possible other values are:

SOCAN_OK : Setting the inhibit time was successful.
SOCAN_PORT_ERR : The port number is invalid
SOCAN_COB_ERR : The CAN object ID is invalid
SOCAN_NOT_EXISTS_ERR : The CAN object doesn't exist.
SOCAN_NOT_OWNED_ERR : The CAN object exists but was defined by a different thread (using a different handle 'hdl').
SOCAN_NOT_WO_ERR : The CAN object is not a write object.

Definition at line 1580 of file socan.c.

◆ socan_set_user_area()

socan_rc socan_set_user_area	(	unsigned char	port,
		unsigned short	cob,
		void *	ptr )

extern

Associate an allocated memory block with a CAN object.

A memory block that was created with malloc() or calloc() is associated with a CAN object with this function. Note that is is imperative that the memory was allocated as described above since socan will call free() on this block when the CAN object is deleted or socan_new_user_area() is called. Note too, that a previously associated memory block is not freed automatically, the application must ensure that there is no memory leak and free the old memory block itself.

Parameters

[in]	port	The port number.
[in]	cob	The CAN object ID.
[in]	ptr	A pointer to the memory block.

Returns

A socan_rc return code, possible other values are:

SOCAN_OK : Setting the inhibit time was successful.
SOCAN_PORT_ERR : The port number is invalid
SOCAN_COB_ERR : The CAN object ID is invalid
SOCAN_NOT_EXISTS_ERR : The CAN object doesn't exist.
SOCAN_NOT_OWNED_ERR : The CAN object exists but was defined by a different thread (using a different handle 'hdl').

Definition at line 1658 of file socan.c.

◆ socan_str_rc()

char * socan_str_rc ( socan_rc rc )

extern

Return a string representation of a socan_rc return code.

Parameters

[in] rc The return code

Returns: A pointer to a constant string

Definition at line 372 of file socan.c.

◆ socan_tracelevel()

int socan_tracelevel ( int level )

extern

Get and/or set the socan trace level.

The trace level determines if and when messages are printed to the console during normal operation. These are the currently known trace print levels:

0: no traces
1: traces in user functions
2: traces in reader/writer

Parameters

[in] level The trace level. If >=0, set this as new trace level. If <0, do not change the trace level, only read it.

Returns: The current or new trace level

Definition at line 354 of file socan.c.

◆ socan_ts_to_str()

socan_rc socan_ts_to_str	(	unsigned long	ts,
		char *	buf,
		int	buflen )

extern

Convert a time stamp to a string.

This function converts the time stamp returned by socan_obj_ts() to a human readable string. The string is stored in the buffer provided as parameter to this function.

Parameters

[in]	ts	The time stamp
[in]	buf	The address of the string buffer
[in]	buflen	The length of the string buffer

Returns

A socan_rc return code, possible other values are:

SOCAN_OK : This value is always returned

Definition at line 1572 of file socan.c.

◆ socan_use_queue()

socan_rc socan_use_queue	(	unsigned char	port,
		unsigned short	cob )

extern

Prepare a CAN object for using socan_queue_read()

The functions socan_readnow() and socan_read() only allow to read from a single CAN object. socan_queue_read() however, waits for incoming data on a number of CAN objects. These CAN objects are not given to socan_queue_read() as a parameter, instead the CAN objects are set up to be used by socan_queue_read() with this function.

Parameters

[in]	port	The port number.
[in]	cob	The CAN object ID.

Returns

A socan_rc return code, possible other values are:

SOCAN_OK : Setting the inhibit time was successful.
SOCAN_PORT_ERR : The port number is invalid
SOCAN_COB_ERR : The CAN object ID is invalid
SOCAN_NOT_EXISTS_ERR : The CAN object doesn't exist.
SOCAN_NOT_OWNED_ERR : The CAN object exists but was defined by a different thread (using a different handle 'hdl').
SOCAN_NOT_RO_ERR : The CAN object is not a read object. Note that remote-read objects (SOCAN_READ_RTR) are not allowed here.

Definition at line 1600 of file socan.c.

◆ socan_user_area()

socan_rc socan_user_area	(	unsigned char	port,
		unsigned short	cob,
		void **	area )

extern

Return memory block associated with a CAN object.

This returns a pointer to the memory block that was previously created with socan_new_user_area(). If there was never a memory created, the function returns a NULL pointer.

Parameters

[in]	port	The port number.
[in]	cob	The CAN object ID.
[out]	area	A pointer to the memory block is returned here.

Returns

A socan_rc return code, possible other values are:

SOCAN_OK : Setting the inhibit time was successful.
SOCAN_PORT_ERR : The port number is invalid
SOCAN_COB_ERR : The CAN object ID is invalid
SOCAN_NOT_EXISTS_ERR : The CAN object doesn't exist.
SOCAN_NOT_OWNED_ERR : The CAN object exists but was defined by a different thread (using a different handle 'hdl').

Definition at line 1642 of file socan.c.

◆ socan_write()

socan_rc socan_write	(	socan_hdl	hdl,
		unsigned char	port,
		unsigned short	cob,
		const void *	data )

extern

Write a SOCAN_WRITE or SOCAN_WRITE_RTR object synchronously.

In case of a SOCAN_WRITE object, the function triggers the writing and waits until the write is finished or a timeout occurs. In case of a SOCAN_WRITE_RTR object, the function simply writes to the internal buffer of the CAN object and returns immediately.

Parameters

[in]	hdl	The handle obtained by socan_open().
[in]	port	The port number.
[in]	cob	The CAN object ID.
[in]	data	A pointer to the data.

Returns

A socan_rc return code, possible other values are:

SOCAN_OK : Setting the inhibit time was successful.
SOCAN_PORT_ERR : The port number is invalid
SOCAN_COB_ERR : The CAN object ID is invalid
SOCAN_NOT_EXISTS_ERR : The CAN object doesn't exist.
SOCAN_NOT_OWNED_ERR : The CAN object exists but was defined by a different thread (using a different handle 'hdl').
SOCAN_NOT_WO_ERR : The CAN object is neither a SOCAN_WRITE nor a SOCAN_WRITE_RTR object.
SOCAN_TIMEOUT : Timeout, writing didn't occur within the timeout time defined with socan_add_obj().
SOCAN_ERROR : Internal error.

Definition at line 1927 of file socan.c.

◆ socan_write_inhibit()

socan_rc socan_write_inhibit	(	socan_hdl	hdl,
		unsigned char	port,
		unsigned short	cob,
		const void *	data,
		unsigned long *	inhibit_time )

extern

Write a SOCAN_WRITE or SOCAN_WRITE_RTR object asynchronously with inhibit time.

In case of a SOCAN_WRITE object, the function triggers the writing and returns immediately if the time passed since the last write is bigger than the inhibit time. If this is not the case, the function returns SOCAN_WAIT and the write is aborted. In case of a SOCAN_WRITE_RTR object, the function simply writes to the internal buffer of the CAN object and returns immediately.

Parameters

[in]	hdl	The handle obtained by socan_open().
[in]	port	The port number.
[in]	cob	The CAN object ID.
[in]	data	A pointer to the data.
[out]	inhibit_time	Time the user task has to wait in microseconds.

Returns

A socan_rc return code, possible other values are:

SOCAN_OK : Setting the inhibit time was successful.
SOCAN_PORT_ERR : The port number is invalid
SOCAN_COB_ERR : The CAN object ID is invalid
SOCAN_NOT_EXISTS_ERR : The CAN object doesn't exist.
SOCAN_NOT_OWNED_ERR : The CAN object exists but was defined by a different thread (using a different handle 'hdl').
SOCAN_NOT_WO_ERR : The CAN object is neither a SOCAN_WRITE nor a SOCAN_WRITE_RTR object.
SOCAN_WAIT : The previous write of this CAN object either is not yet finished or the time passed since then is smaller than the inhibit time. The write request is aborted and the function returns in parameter inhibit_time the time the application has to wait before it can try to write again.
SOCAN_TIMEOUT : The previous write didn't take place in the specified timeout time. This is only a warning, the new write request is issued nonetheless.
SOCAN_ERROR : Internal error.

Definition at line 2072 of file socan.c.

◆ socan_writelater()

socan_rc socan_writelater	(	socan_hdl	hdl,
		unsigned char	port,
		unsigned short	cob,
		const void *	data )

extern

Write a SOCAN_WRITE or SOCAN_WRITE_RTR object asynchronously.

In case of a SOCAN_WRITE object, the function triggers the writing and returns immediately. In case of a SOCAN_WRITE_RTR object, the function simply writes to the internal buffer of the CAN object and returns immediately.

Parameters

[in]	hdl	The handle obtained by socan_open().
[in]	port	The port number.
[in]	cob	The CAN object ID.
[in]	data	A pointer to the data.

Returns

A socan_rc return code, possible other values are:

SOCAN_OK : Setting the inhibit time was successful.
SOCAN_PORT_ERR : The port number is invalid
SOCAN_COB_ERR : The CAN object ID is invalid
SOCAN_NOT_EXISTS_ERR : The CAN object doesn't exist.
SOCAN_NOT_OWNED_ERR : The CAN object exists but was defined by a different thread (using a different handle 'hdl').
SOCAN_NOT_WO_ERR : The CAN object is neither a SOCAN_WRITE nor a SOCAN_WRITE_RTR object.
SOCAN_WAIT : The previous write of this CAN object is not yet finished, writing aborted.
SOCAN_TIMEOUT : The previous write didn't take place in the specified timeout time. This is only a warning, the new write request is issued nonetheless.
SOCAN_ERROR : Internal error.

Definition at line 2000 of file socan.c.

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ COB_NO

◆ SOCAN_FRAME_LENGTH

◆ SOCAN_MAX_PORTS

◆ SOCAN_VERSION_MAJOR

◆ SOCAN_VERSION_MINOR

◆ SOCAN_VERSION_STR

Typedef Documentation

◆ socan_hdl

◆ socan_obj_h

Enumeration Type Documentation

◆ socan_obj_type

◆ socan_rc

Function Documentation

◆ socan_add_obj()

◆ socan_add_port()

◆ socan_close()

◆ socan_del_obj()

◆ socan_errprintlevel()

◆ socan_free_user_area()

◆ socan_init()

◆ socan_new_user_area()

◆ socan_obj_info()

◆ socan_obj_ts()

◆ socan_open()

◆ socan_port_bitrate()

◆ socan_port_device()

◆ socan_queue_read()

◆ socan_rc_is_error()

◆ socan_read()

◆ socan_readnow()

◆ socan_realtime_setup()

◆ socan_set_inhibit()

◆ socan_set_user_area()

◆ socan_str_rc()

◆ socan_tracelevel()

◆ socan_ts_to_str()

◆ socan_use_queue()

◆ socan_user_area()

◆ socan_write()

◆ socan_write_inhibit()

◆ socan_writelater()