Functions

This part describes the Functions that are defined in the simple CAN-interface.

Note that all functions that according to the following description print to the console actually use the dbg module to print. dbg is part of the tool library which is part of MultiCAN. dbg allows to redirect the output to a file or a simple network server, for further details see dbg documentation.

sci_open

sci_Return sci_open(sci_Struc **s_struc, char *app_name,
                    sci_Errcode *err);

This is the open-function for the SCI-library. A process or thread can only use the other functions of the library, when it has once called sci_open.

Parameters and return-codes:

s_struc

This is the pointer to the created sci-structure. The calling program gets a pointer to a new created internal sci-structure. The user program should not read or write to that structure. Since the internal details of this structure are hidden and it’s size is unknown to user, the user program should not define variables of the type sci_Struc but only a pointer to a variable of this type.

app_name

This parameter may be an empty string or a string that identifies the application. In case of an empty-string a new sci-structure is created that is unique for that process (note: not unique for the thread). If the string is not empty, it is stored in the SCI-library. Any program that opens the library with the same string gets the same sci-structure.

err

This is the only function in sci, where the error-code is returned directly and has not to be requested with sci_get_errcode. The user program should have a variable of the type sci_Errcode defined and provide a pointer to that variable with the parameter err.

return value

This function returns either SCI_NOTHING in case of successful execution or SCI_ERROR in case of an error. The error- code can then be found the user’s error-variable, provided by the err parameter.

sci_close

sci_Return sci_close(sci_Struc **s_struc);

This function is used (by a thread) to close the SCI-library. All CAN objects that were previously defined (by that thread) and the sci-structure, are deleted.

Parameters and return-codes:

s_struc

This is the address of a pointer that points to the sci-structure. After successful closing, the internal sci-structure is deleted and the given pointer is changed to a NULL pointer.

return value

This function returns SCI_NOTHING on success, SCI_ERROR in case of an error. In case of an error, the sci-structure remains defined and the pointer to that structure remains valid.

sci_init

sci_Return sci_init(sci_Struc *s_struc,
                    unsigned short port, sci_Bitrate bitrate);

This function initializes a CAN-port with a certain bitrate. In some implementations of sci, a CAN-port cannot be accessed before it has been initialized once with sci_init(). In multitasking implementations of sci, SCI_AUTHORIZE_ERR - error occurs when the current thread is not the first thread that has used the SCI-library, see also the description of SCI_AUTHORIZE_ERR, which is part of the sci_Errcode enumeration type. Portable programs can call sci_init for each port they use and just ignore a possible SCI_AUTHORIZE_ERR - error.

Parameters and return-codes:

s_struc

This is the sci-structure, created by sci_open()

port

This is port that is to be initialized. It depends on your implementation of sci and on your installed CAN interface hardware how many ports are available. Valid port numbers must be greater or equal to zero.

bitrate

This parameter specifies the bitrate for the port. Valid bitrates are defined in the sci_Bitrate data-type.

return value

This function returns SCI_NOTHING in case of success or SCI_ERROR in case of an error.

sci_reset

sci_Return sci_reset(sci_Struc *s_struc, unsigned short port);

This function resets a CAN-port. It is similar in it’s function to sci_init, but the bitrate of the port remains unchanged. All CAN-objects on this port are lost and have to be re-defined. Depending on the underlaying hardware, it may be that it is not possible to reset single CAN-ports independently. The VME-CAN2 card for example, has 2 CAN ports but a card-reset resets both ports. In multitasking implementations of sci, SCI_AUTHORIZE_ERR - error occurs when the current thread is not the first thread that has used the SCI-library, see also the description of SCI_AUTHORIZE_ERR, which is part of the sci_Errcode enumeration type.

Parameters and return-codes:

s_struc

This is the sci-structure, created by sci_open()

port

This is port that is to be initialized. It depends on your implementation of sci and on your installed CAN interface hardware how many ports are available. Valid port numbers must be greater or equal to zero.

return value

This function returns SCI_NOTHING in case of success or SCI_ERROR in case of an error.

sci_get_bitrate

sci_Return sci_get_bitrate(sci_Struc *s_struc,
                           unsigned short port, sci_Bitrate *bitrate);

This function returns the bitrate that was set for a specific port. The port-parameter may be a real-port or a plug-port. The bitrate is returned in the bitrate parameter.

Parameters and return-codes:

s_struc

This is the sci-structure, created by sci_open()

port

This is port that is to be examined. This may also be a plug-port, in this case the bitrate of the corresponding real-port is returned.

bitrate

The current bitrate is returned via this parameter. Note that the type of this variable is not int but sci_Bitrate.

return value

This function returns SCI_NOTHING in case of success or SCI_ERROR in case of an error.

sci_get_errcode

sci_Return sci_get_errcode(sci_Struc *s_struc, sci_Errcode *errcode);

This function returns the last valid error-code for a thread. It is typically called immediately after another sci-function returned the SCI_ERROR flag. If another sci_function is called after the error but before sci_get_errcode(), the original errorcode is lost.

Parameters and return-codes:

s_struc

This is the sci-structure, created by sci_open()

errcode

This is a pointer to a variable of the type sci_Errcode that is defined in the user program. The current errorcode for the current thread is written to that user-variable.

return value

This function always returns SCI_NOTHING.

sci_get_object

sci_Return sci_get_object(sci_Struc *s_struc, sci_Object **object,
                          unsigned short port, int id)

This function returns the sci_Object for a given port number and CAN object id.

Parameters and return-codes:

s_struc

This is the address of a pointer that points to the sci-structure that was created by sci_open.

object

This is the address of a pointer to an sci-object. After successful execution of this function the pointer points to the sci_Object.

port

This is the port-number of the CAN-object.

id

This is the CAN-id of the object.

return value

This function returns either SCI_NOTHING in case of successful execution or SCI_ERROR in case of an error.

sci_get_user

void *sci_get_user(sci_Object *object)

Get user part of an sci_Object.

This function returns the user part, a pointer to a data structure managed by the application that uses sci.

Parameters and return-codes:

object

The sci_Object pointer.

return value

A void pointer to the user part.

sci_get_info

sci_Return sci_get_info(sci_Struc *s_struc, sci_Object *object,
                        unsigned short *port, int *id, int *length,
                        int *timeout, sci_Object_Type *type)

This function returns the properties of a sci-object. With this function it is possible to get all properties of an object, that were specified with the call of sci_init_object, back.

Parameters and return-codes:

s_struc

This is the sci-structure, created by sci_open()

object

This is a pointer the sci-object that is to be examined.

port

This is a pointer to an integer-variable of the user program. The port-number of the object is written to that variable.

id

This is a pointer to an integer-variable of the user program. The CAN-id of the object is written to that variable.

length

This is a pointer to an integer-variable of the user program. The length of the object is written to that variable.

timeout

This is a pointer to an integer-variable of the user program. The timeout that was specified for that object is written to this variable.

type

This is a pointer to a variable of the type sci_Object_Type that should be defined in the user program. The type of the sci-object is written to this variable.

return value

This function always returns SCI_NOTHING on success and SCI_ERROR in case of an error (e.g. when object is a NULL pointer).

sci_get_timestamp

sci_Return sci_get_timestamp(sci_Struc *s_struc, sci_Object *object,
                             unsigned long long *pstamp, int *pvalid,
                             unsigned char *mode, unsigned char *irq_cnt)

This function returns the timestamp of an sci-write object. The timestamp is set, when the write operation on the CAN bus actually takes place. It is an integer of type long long (64 bits), where the value 0 defines the time when the IOC was booted. Note that the timestamp may be invalid. This is the case when a write operation is in progress but not yet completed.

Parameters and return-codes:

s_struc

This is the sci-structure, created by sci_open()

object

This is a pointer the sci-object that is to be examined.

pstamp

This is a pointer to an integer-variable of type long long in the user program. The timestamp is is written to that variable.

pvalid

This is a pointer to an integer-variable of the user program. If the timestamp is valid, a non-zero value is written to that variable. 0 is written to that variable when the timestamp is invalid.

mode

This is a pointer to an unsigned char variable. Here the function returns the internal timestamp mode of VCAN.

irq_cnt

This is a pointer to an unsigned char variable. Here the function returns the internal VCAN interrupt counter of the CAN object.

returns

This function always returns SCI_NOTHING on success and SCI_ERROR in case of an error.

sci_obj_dump_buf

sci_Return sci_obj_dump_buf(char *buf,
                            sci_Struc *s_struc, sci_Object *object);

Prints information about the object to a string buffer. The information includes the CAN-id, length, timeout, port and object type. The buffer buf must have room for 80 characters.

Parameters and return-codes:

buf The address of an array of characters, at least 80 characters long.

s_struc

This is the sci-structure, created by sci_open()

object

This is a pointer the sci-object that is to be examined.

sci_obj_dump

sci_Return sci_obj_dump(sci_Struc *s_struc, sci_Object *object);

Prints information about the object to the console. The information includes the CAN-id, length, timeout, port and object type.

Parameters and return-codes:

s_struc

This is the sci-structure, created by sci_open()

object

This is a pointer the sci-object that is to be examined.

sci_init_object

sci_Return sci_init_object(sci_Struc *s_struc, sci_Object **object,
                           unsigned short port, int id, int length,
                           int timeout, sci_Object_Type type, void *userp)

This function initializes a single CAN-object. A sci-object structure is created that is used by all other sci functions that work on single CAN-objects. Note that each sci-object contains a user part that can be used to store user-defined data for each object. See also the description of the type sci_Object.

If there was already an sci_Object defined for that CAN-id, sci_init_object() either returns an error if the object’s properties do not exactly match the already defined object, or it duplicates the already existing object. A SCI_EXISTS-flag signals that an already existing sci-object was found. For a description of duplicated objects see also sci_dup_object().

Note that the user-part of the sci_Object (see also description of this data-type) is initialized with zero- bytes. Note too, that remote-write objects are initialized with a number of zero-bytes that correspond to the object’s length and can be read by another CAN participant from that moment on.

Parameters and return-codes:

s_struc

This is the sci-structure, created by sci_open()

object

This is the address of a pointer to an sci-object. After successful execution of this function the pointer points to the new created sci_Object.

port

This is the port-number of the CAN-object.

id

This is the CAN-id of the object.

length

This is a the length of the CAN-object. The object is defined with a certain length, that can range from 0 to 8 bytes. If data with a different number of bytes is received from the CAN bus, the appropriate read-functions will return a SCI_LENGTH_ERR.

timeout

This is the timeout the object. The timeout is specified in milliseconds and can range from 0 to 32767. The timeout is useful for sci-functions that would otherwise never return in case of an error. An example for such a function is sci_read, this function waits for new data, if no new data arrives, it returns after the given timeout. Note that there are some sci-functions that do not need and do not use timeouts specified for a given object, an example for this is sci_read_now, this function returns immediately and does never wait for new data to arrive. Note also that remote-write objects (type SCI_REMOTE_WRITE) have no timeout. Any given timeout for this object-type is ignored.

type

This is the type of the object, there are basically 4 types of objects which can be distinguished as read or write, remote or not-remote objects. These types are described in with the sci_Object_Type in this documentation.

userp

This is an arbitrary pointer that is stored in the sci_Object. If you don’t need this, just set this to NULL.

return value

This function returns SCI_NOTHING in case of success. If wrong parameters were given, it returns the SCI_ERROR-flag. SCI_EXISTS signals that there was already an sci-object defined for the given CAN-id. If the new object properties do not match the ones of the already defined object, SCI_ERROR is returned, too. In this case the error-code that can be requested with the sci_get_errcode() function shows this first object property that did not match (e.g. SCI_LENGTH_ERR: the lengths were different).

sci_dup_object

sci_Return sci_dup_object(sci_Struc *s_struc, sci_Object **dup_object,
                        sci_Object *object, void *userp)

This function duplicates an existing sci-object. The second sci-object has exactly the same properties as the original object. However, the user part of the sci-object structure is duplicated and is independent from the user-part of the original object. Both sci-objects, the old and the new one can then be used to read or to write to a certain CAN-object. There is, from the users point of view, no difference between the original and the duplicated object. Each object can be deleted separately without interference with the other one. There is only one point, were a difference is made between duplicated objects, that is the event-object mechanism. Event-objects are used to either start a user-defined callback function or to make sci_queue_read() return. Both, the callback-function and sci_queue_read() get a pointer to the sci-object where the event took place. Since it is possible that one CAN-object has several associated duplicated sci-objects, a decision has to be made which one is returned for the event-mechanism. This object is defined with the sci_set_callback - function. For a given set of duplicated objects, only one can be the event-object.

Parameters and return-codes:

s_struc

This is the sci-structure, created by sci_open()

dup_object

This is the address of a pointer to an sci-object. After successful execution of this function the pointer points to the new created sci_Object.

object

This is the address of a pointer to an sci-object. After successful execution of this function the pointer points to the new created sci_Object.

userp

This is an arbitrary pointer that is stored in the duplicated sci_Object. If you don’t need this, just set this to NULL.

return value

This function returns SCI_NOTHING in case of success or SCI_ERROR in case of a parameter error (e.g. when object is a NULL pointer).

sci_delete_object

sci_Return sci_delete_object(sci_Struc *s_struc, sci_Object **object);

This function deletes an sci-object. It removes the internal sci_Object- structure and makes the CAN-id on the CAN interface available again. When this function is performed on duplicated objects, the other duplicated object for the same CAN-object remain unchanged.

Parameters and return-codes:

s_struc

This is the sci-structure, created by sci_open()

object

This is the address of a pointer to an sci-object. After successful execution, the internal object-structure is deleted and the given pointer is changed to a NULL pointer.

return value

This function returns SCI_NOTHING on success, SCI_ERROR in case of an error.

sci_set_inhibit

sci_Return sci_set_inhibit(sci_Struc *s_struc, sci_Object *object,
                           unsigned long inhibit_time)

This function sets the inhibit-time for a CAN object. The main application for inhibit-times is communication with slow CAN devices that are not able to process CAN object’s at the maximum possible speed. For example with a 1 MBit/s CAN line, a CAN frame can be physically sent about every 130 microseconds. If the other CAN participant can only process one frame every 1000 microseconds, inhibit-times can be used to limit the rate of transmission. The inhibit-time is the minimal allowed time between two writes to a CAN-write object. This function should only be applied to ordinary CAN-write objects. The inhibit-time has only an effect when sci_write_inhibit() is used instead of sci_write() to write to the CAN object. In current implementations of sci the inhibit-time of a new created CAN object is 0 but an application should not rely on that. See also the description of sci_write_inhibit().

Parameters and return-codes:

s_struc

This is the sci-structure, created by sci_open()

object

This is the address of a pointer to an sci-object. The object must be an ordinary write-object (not a remote-write object).

inhibit_time

This is the inhibit-time for the CAN object. Note that the inhibit-time (in opposition to timeout-times) is specified in microseconds.

return value

This function returns SCI_NOTHING on success, SCI_ERROR in case of an error. Note that the attempt to set an inhibit-time on an object that is not an ordinary write-object causes an error.

sci_read_now

sci_Return sci_read_now(sci_Struc *s_struc, sci_Object *object,
                        char *data);

In general, this function reads data from a can-object without waiting (‘now’). This function can be applied to read and remote-read objects but not event-objects. It’s function, however is different for each object-type:

  • For ordinary read objects, this functions just reads data from the internal buffer that is always available on the CAN interface. The returned flags, however, indicate whether the data has already been read before or is really new.

  • For remote-read objects, this function should be used in conjunction with sci_write(). sci_write() sends the remote-request while sci_read_now is used to read the reply. Although then the remote-request has already been sent, it may be, that sci_read_now has to wait some time for the answer. If the hardware of the answering CAN device is okay, the answer should be received within a millisecond. However, when there is an hardware error on the other CAN device, an answer will never come. For this reason, the function will return with an timeout-error after the timeout that was specified (with sci_init_object()) with the given sci-object.

Parameters and return-codes:

s_struc

This is the sci-structure, created by sci_open()

object

This is the sci-object that is to be read.

data

This is a pointer to the area where the data has to be written. This pointer should be the address of a data-buffer that is defined in the user-program. 0 to 8 bytes are written on this address, the number depends on the length with which the object was defined (see also sci_init_object()).

return value

This function returns SCI_NOTHING in case of success or SCI_ERROR in case of an error. It returns SCI_OLD_DAT when the data has already been read before, but the data is copied anyway to the address the user has given.

sci_read_new

sci_Return sci_read_new(sci_Struc *s_struc, sci_Object *object,
                        char *data);

This function is similar to sci_read_now but it does not write to the memory area data points to unless there was new data. Note that this function, like sci_read_now does return immediately without waiting. Note also, that this function works identical with sci_read_now when it is used with remote-read objects. This function cannot be used with event-objects.

Parameters and return-codes:

s_struc

This is the sci-structure, created by sci_open()

object

This is the sci-object that is to be read.

data

This is a pointer to the area where the data has to be written. This pointer should be the address of a data-buffer that is defined in the user-program. 0 to 8 bytes are written on this address, the number depends on the length with which the object was defined (see also sci_init_object()). The data is only written if it is found to be new.

return value

This function returns SCI_NOTHING in case of success or SCI_ERROR in case of an error. It returns SCI_OLD_DAT when the data has already been read before. In this case, the data is not copied to the address the user has given.

sci_read

sci_Return sci_read(sci_Struc *s_struc, sci_Object *object,
                    char *data);

This function reads data from a can-object, but it may wait for some time (see also sci_read_now()). This function can be applied to read and remote-read objects but not event-objects. It’s function is different for each of the two object-types:

  • For ordinary read objects, this function returns when it finds data in the object’s data buffer, that has not yet been read. If the data has already been read, the function waits for new data from the CAN bus. If no new data arrives after the object’s timeout-time (specified with sci_init_object()) it returns with a timeout-status. The returned flags indicate whether the data is new (not yet read) or old (already read). Note that a timeout is not an error, but is just signalled by the SCI_TMOUT-flag, in this case the old data from the object’s data buffer is returned.

  • For remote-read objects, this function sends a remote-request and waits for the answer from another CAN device. If set up correctly, the other CAN device should send an answer together with new data back, this data is then returned by sci_read(). If no CAN device sends an answer within the object’s timeout-time (specified with sci_init_object()), a timeout-error is returned. Note that this is (see above) a real sci-error and not a just a status.

Parameters and return-codes:

s_struc

This is the sci-structure, created by sci_open()

object

This is the sci-object that is to be read.

data

This is a pointer to the area where the data has to be written. This pointer should be the address of a data-buffer that is defined in the user-program. 0 to 8 bytes are written on this address, the number depends on the length with which the object was defined (see also sci_init_object()). The data is only written if it is found to be new.

return value

This function returns SCI_NOTHING in case of success or SCI_ERROR in case of an error. Since this function waits for new data to arrive, it can return with a timeout when there was no new data within the timeout that was set for the object (see sci_init_object()). The timeout is not an error, a timeout causes the SCI_TIMEOUT flag to be returned, together with SCI_OLD, the returned data is just the old data that was found in the internal buffer from the previous transmission.

sci_queue_read

sci_Return sci_queue_read(sci_Struc *s_struc, sci_Object **object,
                          char *data)

Please note that non-multitasking implementations of sci (e.g sci for embedded controller) do not support sci_queue_read (see further below for datails).

sci_queue_read reads data from an event-object. This function waits until an event takes place and returns the corresponding object-pointer and the new data.

Here are some advantages of using sci_queue_read:

  • The objects do not have to be specified when the function is called. They are implicitly known; all event object that have ever been defined for the current thread (=process) are used.

  • The number of objects is only limited to the number your hardware supports. Objects on different ports can be used (the port is defined with sci_init_object()).

  • This function can be used on read and remote-read objects. An answer on a remote-request is also an event and is recognized when the remote-read object is also an event-object. Note that sci_queue_read() does not send the remote-request, that has to be done separately (with sci_write().

  • There is, in general, no timeout watch for event-objects. Any timeouts that were specified in the object’s initialization, are ignored. sci_queue_read() will always wait for events on all event objects that are defined for the current thread (=process).

  • Event-objects have to be initialized before the call sci_queue_read() by calling sci_set_callback(). In order to set-up event-objects for queue-read (instead of callback), the provided callback-function pointer for sci_set_callback() has to be a NULL-pointer.

  • Since this function is based on the use of a semaphore, it is not available on single-tasking implementations of sci, like the MS-DOS implementation.

Parameters and return-codes:

s_struc

This is the sci-structure, created by sci_open()

object

This is the address to a pointer where the sci-object pointer of the object is stored, where the event was detected.

data

This is a pointer to the area where the data has to be written. This pointer should be the address of a data-buffer that is defined in the user-program. 0 to 8 bytes are written on this address, the number depends on the length with which the object was defined (see also sci_init_object()). The data is only written if it is found to be new.

return value

This function returns SCI_NOTHING in case of success or SCI_ERROR in case of an error. It’s return-codes are identical to the return-codes of sci_read() except that no timeouts can occur.

sci_write

sci_Return sci_write(sci_Struc *s_struc, sci_Object *object, char *data);

This function writes data to a sci-object. This function can be applied to write, remote-write and remote-read objects. It’s function however is different for each object-type:

  • For ordinary write objects, this function writes data to the CAN bus. It depends on your implementation of sci whether the actual writing is done immediately or whether your hardware writes the data later independently from your program. If data is written immediately, sci_write() can detect when the writing failed and return an appropriate error-code. If data is written later, errors cannot be detected immediately, but only when sci_write() is called again. In this case a previously failed write will case sci_write() to return an error.

  • For remote-write objects, data is just written to the object’s data buffer. The data will only be sent to the CAN bus when a remote-request is received. This physical sending will be performed by the CAN hardware, independently of the software.

  • For remote-read objects, just a remote-request is sent. The data parameter is ignored in this case. In order to receive the answer from another CAN-device for the remote-request you have to use sci_read_now() or the one of the two event-object mechanisms (for more details on this see also sci_set_callback() and sci_queue_read()).

Parameters and return-codes:

s_struc

This is the sci-structure, created by sci_open()

object

This is the sci-object that is to be written to.

data

This is a pointer to the area from where the data has to be read. This pointer should be the address of a data-buffer that is defined in the user-program. 0 to 8 bytes are written, this depends on the object’s length which was defined with sci_init_object(). If sci_write() is used with remote-read objects, the data-parameter is ignored.

return value

This function returns SCI_NOTHING in case of success or SCI_ERROR in case of an error.

sci_write_inhibit

sci_Return sci_write_inhibit(sci_Struc *s_struc, sci_Object *object,
                             char *data, unsigned long *rest_time)

This function is similar to sci_write(). It writes data to a sci-object and can only be applied to ordinary write-objects. sci_write_inhibit() should be used in conjunction with sci_set_inhibit() which defines an inhibit-time for a single CAN-object (note that upon creation of a CAN-write object, it’s inhibit-time is 0). sci_write_inhibit() fails when the time since the last write to the CAN-object is less than the inhibit-time for that object. In this case, it returns the time that the user has to wait, before he is allowed to write again to the object. The purpose of this function is communication with slow CAN participants that can only handle a certain number of CAN frames per second (See also the description of sci_set_inhibit()). Note that this function does not wait itself when the inhibit-time has not yet passed but returns immediately without writing in this case. It is the task of the user-program to wait the right amount of time.

Parameters and return-codes:

s_struc

This is the sci-structure, created by sci_open()

object

This is the sci-object that is to be written to. This must be an ordinary write-object.

data

This is a pointer to the area from where the data has to be read. This pointer should be the address of a data-buffer that is defined in the user-program. 0 to 8 bytes are written, this depends on the object’s length which was defined with sci_init_object().

rest_time

This is the time the user program has yet to wait before it can write to the CAN object again. The time is written to a variable of the type unsigend int, whose address is given by this parameter. This variable should only be evaluated, when sci_write_inhibit() returns SCI_WAIT in it’s return-value. Note that the time discussed here is given in microseconds.

return value

This function returns SCI_NOTHING in case of success or SCI_ERROR in case of an error. If the writing did not take place because the time since the last write was smaller than the inhibit-time, the SCI_WAIT-flag is returned.

sci_set_callback

sci_Return sci_set_callback(sci_Struc *s_struc, sci_Object *object,
                            sci_Callback_Func f);

This function defines an event-object. These are needed if you want to use sci_queue_read() which waits until an event takes place and returns the corresponding object-pointer and the new data.

An event-object can only be defined once. Its properties cannot be changed later. However, event object can be deleted with sci_delete_object(). An attempt to define the event-object again will result in an SCI_SET_CALLB_ERR - error. Note that for duplicated objects (objects created with sci_dup_object() or sci_init_object(), only one of all the objects associated with the same CAN-id can become an event-object.

Parameters and return-codes:

s_struc

This is the sci-structure, created by sci_open()

object

This is the sci-object that has to become an event-object.

f

This is a legacy parameter that is no longer used. It must always be NULL.

return value

This function returns SCI_NOTHING in case of success or SCI_ERROR in case of an error.

sci_def_plug_in

sci_Return sci_def_plug_in(unsigned short plug_port,
                         unsigned short real_port,
                           sci_Plug_Func h2l, sci_Plug_Func l2h,
                           sci_Plug_Lencalc lcalc,
                           sci_Errcode *err)

This function defines an plug-in. Plug-ins do data-conversions of the data that is transmitted to and from CAN objects. The 2 data-formats between this conversion takes place are also called the low-level- (raw CAN-bus-data) and the high-level (sci-application data) format.

A plug-in consists of 3 functions, 2 of these functions perform the data-conversion in both directions and a third function calculates the length of the low-level data in dependence of the length of the high-level data. See also the description the data-types sci_Plug_Func and sci_Plug_Lencalc.

A plug-in also defines a plug-port. A plug-port can be used like a real CAN-bus port but each access to the plug-port (e.g. reading or writing to CAN objects that are defined for that port) involves the plug-in data-conversion functions. Each plug-port is connected with a real-port that represents the physical CAN-bus connection that is used when that plug-port is accessed.

Note that this is one of the rare functions that do not have a sci_struc parameter. This function can be called without calling sci_open first. This also means that the plug-ins that one user process defines are valid for all other user processes. Currently, plug-ins cannot be deleted, once they have been defined for one plug-port. They remain valid as long as the sci-library or the program that is linked with the sci-library is loaded.

Parameters and return-codes:

plug_port

This is the plug-port for which the plug-in is defined. A plug-port must be in the range of SCI_PLUGPORT_START and SCI_PLUGPORT_START+SCI_MAX_PLUGPORTS-1. That plug-port can, after successful execution of sci_def_plug_in, used like any other port.

real_port

This is real-port that the plug-port is connected to. Each access of the plug-port will first involve the plug-in data conversion and then access the real-port.

h2l

This is data-conversion function that converts the high-level data-format to the low-level data format.

l2h

This is data-conversion function that converts the low-level data-format to the high-level data format.

lcalc

This is the length-conversion function that calculates the length of the low-level data in dependence of the length of the high-level data. lcalc may return 0 when a certain high-level data-length cannot be converted by the plug-in functions. Note that each supported high-level data-length must correspond with just one low-level data-length. This low-level data-length is returned by the length-calculation function lcalc.

err

This is a pointer to a variable of the type sci_Errcode that is defined in the user program. If an error is detected, the errorcode is stored in that user-variable.

return value

This function returns SCI_NOTHING in case of success, SCI_ERROR in case of an error. If an error occured, the errorcode is (see above) stored in the variable that was given by the err -parameter.

sci_predef_dump

int sci_predef_dump(void);

This dumps the internal predef-monitor structure. A monitor causes all read- and write activity on a CAN object to be printed to the console. This function shows which CAN objects have monitors defined. Monitors can be defined before the actual CAN objects are created.

return value

This function always returns 0

sci_monitor_enable

void sci_monitor_enable(void);

This function globally enables printing of monitored CAN objects. As a default, monitors are already globally enabled, so you need to call this function only when sci_monitor_disable was called.

sci_monitor_disable

void sci_monitor_disable(void);

This function globally disables printing of monitored CAN objects. As a default, monitors are already globally enabled.

sci_monitor_wait_enable

void sci_monitor_wait_enable(void);

This switches the “wait enable” function for monitors on. With “wait enable”, when sci_write_inhibit cannot write due to the inhibit time, the internal timestamp the the time still to wait are printed.

sci_monitor_wait_disable

void sci_monitor_wait_disable(void);

This switches the “wait enable” function for monitors off. See also sci_monitor_wait_enable.

sci_set_monitor

int sci_set_monitor(int id, int port, int do_monitor);

This function switches a monitor on for a given CAN object. When a monitor is defined for a CAN object, all read- and write accesses are printed to the console. A monitor can be defined even before sci_init_object was called for that object.

Parameters and return-codes:

id

This is the CAN-id of the object.

port

This is the port-number of the CAN-object.

do_monitor

If this value is 1, the monitor is switched on, if it is 0, the monitor is switched off.

sci_str_status

char *sci_str_status(sci_Return flag);

This function converts a status code from a sci_Return variable to a string. The string can be used to print a return code in a human readable form.

Parameters and return-codes:

flag

The return code we want tp convert to a string.

return value

A character pointer that is the address of a string that repesents the return code.

sci_print_status

void sci_print_status(sci_Return flag);

This function prints a given status code from a sci_Return variable as a string.

Parameters and return-codes:

flag

The return code we want tp convert to a string.

sci_str_err

char *sci_str_err(sci_Errcode err);

This function converts an error code from a sci_Errcode variable to a string. The string can be used to print an error code in a human readable form.

Parameters and return-codes:

err

The error code we want to convert.

return value

A character pointer that is the address of a string that repesents the error code.

sci_print_err

void sci_print_err(sci_Errcode err);

This function prints an error code from a sci_Errcode variable as a string.

Parameters and return-codes:

err

The error code we want to print.

sci_str_bitrate

char *sci_str_bitrate(sci_Bitrate bitrate);

This function converts a bitrate from a sci_Bitrate variable to a string. The string can be used to print a bitrate in a human readable form.

Parameters and return-codes:

err

The bitrate we want to convert.

return value

A character pointer that is the address of a string that repesents the bitrate.

sci_print_bitrate

void sci_print_bitrate(sci_Bitrate bitrate);

Prints a bitrate constant as a string.

Parameters and return-codes:

bitrate

The bitrate to print.

sci_print_obj_struc

void sci_print_obj_struc(sci_Object *object);

This prints information on the given sci_Object to the console.

Parameters and return-codes:

object

The sci_Object to print.

sci_print_thread_struc

void sci_print_thread_struc(sci_Struc *s_struc);

Print some data that sci stores in the sci_Struc data structure to the console. An sci_Struc is intended to be held by each thread that uses sci.

Parameters and return-codes:

s_struc:

The sci_Struc that contains the information.

sci_print_thread_strucs

void sci_print_thread_strucs(void);

Print data that sci stores in all it’s sci_Struc data structures to the console.

get_sci_Struc

sci_Struc *get_sci_Struc(int index);

Returns the sci_Struc by it’s index. This is for debugging purposes only.

Parameters and return-codes:

index

The index of the sci_Struc, starting with 0.

return value

A pointer to an sci_Struc variable.

sci_show_dbg

int sci_show_dbg(void);

This prints the debug options sci was compiled with to the console.

Parameters and return-codes:

return value

This function always returns 0.

sci_help

int sci_help(void);

This function prints a short help text for all debugging functions that are intended to be run interactively.

Parameters and return-codes:

return value

This function always returns 0.

sci_dbg_assert

void sci_dbg_assert(int i);

This function defines what should happen after a failed assertion.

Parameters and return-codes:

i

Assertion handling parameter. 0: No assertions are checked, 1: Just print a message, 2: Print a message and enter infinite loop, 3: Print a message and exit the task.

sci_dbg_tracelevel

void sci_dbg_tracelevel(int i);

Set the trace level.

Parameters and return-codes:

i

Possible values: 0: no tracing at all, 1: messages on fatal errors, 5: messages whenever a function is entered or left, 6: like level 5 but more messages from within functions.