Introduction

Garz & Fricke Industrieautomation GmbH - GFCAN32

Introduction

GFCan32 is a function-library for 32-bit Windows environment, especially Windows CE. Because of that, this manual contains descriptions for library functions under Windows CE.

In cooperation with a device-driver for the operating system for the respective CAN-Controller, GFCan32 supports applications with low-level access to the CAN-bus.

The library is delivered as standard Windows-DLL (dynamic link library) and exports all functions in standard C-convention. Therefore all functions can be called from standard development systems under Windows. The library comprehends code examples for Microsoft Visual C++ and Borland Delphi. For any other development environment the respective manuals have to be considered to their calls of functions in DLLs.

If you are using the driver and the library, the manual of the CAN-controller is to be used as leading documentation. Furthermore, hints and examples of added source codes have to be analyzed.

This document contains information about the full functionality of the GF3CAN32-library. It is NOT a documentation of the working base of the CAN-bus. For that purpose, special documentation has to be consulted.

Copyright © 2000-2004, Garz & Fricke GmbH, Hamburg


Structure and functions of the library

Structure and appliance of the library

The block diagram (Fig.1) shows the design and functionality of the library and its interaction with the driver and hardware.

For a working system three components are always necessary:

  • Function library GFCan32

  • Kerneldriver / VxD for the respective operating system

  • CAN-hardware

GFCan32 works fully interrupt-driven. To receive a maximum of performance within an application, programs should not access directly to the registers of the CAN-controller. The direct-accessing functions are only for testing purposes.

A message-buffer with 256 entries (512 entries for Windows CE) is implemented in the driver. This buffer works as FIFO-buffer. Received messages are transferred to the receive-buffer by interrupt-function. If a message should be sent, the driver tries to deliver it directly at once. If the receiving buffer at the other end is still busy, the message will be stored into the send-buffer until it can be delivered.

The sending part of the controller initiates an interrupt after sending a message and the interrupt-function transceives the next message from the send-buffer.

The receive-buffer activates a background-thread that takes control over the message and transmits it as parameter of a callback-function of the application. This method allows application and driver an effective usage of CPU-time. Especially applications do not need to wait for incoming messages or poll the message-buffer. They only have to register their message-processing functions as a callback-function at the library. The callback-function will then be executed in another thread.

The following steps have to be executed to use GFCan32 within an application:

  • Reset of the CAN-hardware

  • Setting the transfer speed (BAUD-rate)

  • Registering the CAN-callback

  • Initializing of the CAN-controller in a valid descriptor for the message-filtering

  • Activation of the background-thread

  • Processing messages

(Fig. 1 - Schematic illustration of the GFCan32API)


CanGetBaudrate

CanCreateDevice

Creates a new instance of the CANPort controller structure in the library and opens the port of the driver. This function must be executed before any other function is used. Its return value has to be passed as first parameter to all following functions.

Syntax:

BOOL

CanCreateDevice

(

LPCTSTR szDeviceName,

int MslLength

)

Parameters:

szDeviceName
Name of the CAN port that should be opened. The name consist of "CAN" and a consecutive number from 1 to 9. For example "CAN1" for the first CAN port of the system.

MslLenght

Size of the message-buffer in the library in messages. This parameter is unused in Windows CE.

This parameter does not exist on Raytheon boards!

Return values:

If successful, a thread-handle of the new created CAN device will be returned. This value is passed as first parameter to all other functions and must not be changed by the application.

If errors occur, INVALID_HANDLE_VALUE will be returned and informations about the error are available in the following call of ►CanGetLastError.

After a successful call of CanCreateDevice, the function ►CanGetLastError MUST be called, to assure that the physical port has been opened. Only if zero is returned the CAN system is fully operational.

Remarks:

Windows CE does not support additional message buffers, so the second parameter can be ignored on such systems.

Requirements:

Windows NT/2000/XP | Version NT 4.0 or later
Windows 95/98/Me | Version 95 or later
Windows CE | Version 3.0 or later
Header: | Declared in gfcanapi.h / gfcanapiCE.h.
Import Library: | gfcan32.lib, gfcan32CE.lib. (for MS Visual C++)

Supported platforms:

= function available [image] = function not available
 | WindowsCE | Flashn'Go BIOS
Albany |  |
Darling |  |
Kimberly |  |
MaunaKea |  |
Mt.Ziel |  |
Pitcairn |  |
TU400 |  |
Tasmania |  |
TMW Siemens EIB |  |


cancallback

CanCallback

This function is an application-defined callback function that processes the incoming CAN messages

Syntax:

BOOL

CanCallback

(

LPVOID msg

)

Parameters:

msg
Contains the address of the message that has been received. The message is saved as structure with the type CAN_MESSAGE / CAN_MESSAGE_EX. The Application must execute a conversion of the type from LPVOID to PCAN_MESSAGE / PCAN_MESSAGE_EX.

Return values:

This function has no return value

Remarks:

This function is designed as placeholder only. The application has to provide this function and also has to register it with CanRegisterCallback at the library. To delete a registered callback function, CanRegisterCallback can be called either with a new address or with NULL.

To controllers supporting long identifiers the address can be given with a CAN_MESSAGE_EX-structure. Other controllers demand a CAN_MESSAGE-structure.

Requirements:

Windows NT/2000/XP | Version NT 4.0 or later
Windows 95/98/Me | Version 95 or later
Windows CE | Version 3.0 or later
Header: | -
Import Library: | -

Supported platforms:

= function available [image] = function not available
 | WindowsCE | Flashn'Go BIOS
Albany |  |
Darling |  |
Kimberly |  |
MaunaKea |  |
Mt.Ziel |  |
Pitcairn |  |
TU400 |  |
Tasmania |  |


CanCloseDevice

CanCloseDevice

Closes the device opened by there CanCreateDevice function

Syntax:

BOOL

CanCloseDevice

(

HANDLE hDevice

)

Parameters:

hDevice
Handle of the CAN device, that is created in the library. Will be returned via ►CanCreateDevice.

Return values:

If successful, the returned value is non-zero. If errors have occurred, zero will be returned. Informations about the error can be retrieved by a following call of ►CanGetLastError.

Remarks:

None.

Requirements:

Windows NT/2000/XP | Version NT 4.0 or later
Windows 95/98/Me | Version 95 or later
Windows CE | Version 3.0 or later
Header: | Declared in gfcanapi.h / gfcanapiCE.h.
Import Library: | gfcan32.lib, gfcan32CE.lib. (for MS Visual C++)

Supported platforms:

= function available [image] = function not available
 | WindowsCE | Flashn'Go BIOS
Albany |  |
Darling |  |
Kimberly |  |
MaunaKea |  |
Mt.Ziel |  |
Pitcairn |  |
TU400 |  |
Tasmania |  |


CanFlushBuffer

CanFlushBuffer

Empties the sendbuffer of the driver and sends all messages

Syntax:

BOOL

CanFlushBuffer

(

HANDLE hDevice

)

Parameters:

hDevice
Handle of the CAN device, that is created in the library. Will be returned via ►CanCreateDevice.

Return values:

If successful, the returned value is non-zero. If errors have occurred, zero will be returned. Informations about the error can be retrieved by a following call of ►CanGetLastError.

Remarks:

During sending, all messages are stored into a FIFO buffer of the driver. From this FIFO buffer the messages are sent interrupt-controlled to the CAN-bus, as soon as the controller is available again.

This function empties the FIFO buffer and returns not until the last message is sent. The process of sending the messages is monitored by a timeout. If the transmission of a message exceeds this time, the transmission will be aborted. In most cases a bus error can be assumed.

Requirements:

Windows NT/2000/XP | Version NT 4.0 or later
Windows 95/98/Me | Version 95 or later
Windows CE | Version 3.0 or later
Header: | Declared in gfcanapi.h / gfcanapiCE.h.
Import Library: | gfcan32.lib, gfcan32CE.lib. (for MS Visual C++)

Supported platforms:

= function available [image] = function not available
 | WindowsCE | Flashn'Go BIOS
Albany |  |
Darling |  |
Kimberly |  |
MaunaKea |  |
Mt.Ziel |  |
Pitcairn |  |
TU400 |  |
Tasmania |  |


CanGetBitTiming

CanGetBaudrate

Reads the baudrate of the selected CAN interface

Syntax:

BOOL

CanGetBaudrate

(

HANDLE hDevice,

int *baud

)

Parameters:

hDevice
Handle of the CAN device, that is created in the library. Will be returned via ►CanCreateDevice.

*baud

Address of an integer variable. The driver assigns the current used Baudrate to this variable. The value is the Baudrate in kBaud. ►CanSetBaudrate sets a new Baudrate.

Return values:

If successful, the returned value is TRUE. If errors have occurred, FALSE will be returned. Informations about the error can be retrieved by a following call of ►CanGetLastError.

Remarks:

None.

Requirements:

Windows NT/2000/XP | Version NT 4.0 or later
Windows 95/98/Me | Version 95 or later
Windows CE | Version 3.0 or later
Header: | Declared in gfcanapi.h / gfcanapiCE.h.
Import Library: | gfcan32.lib, gfcan32CE.lib. (for MS Visual C++)

Supported platforms:

= function available [image] = function not available
 | WindowsCE | Flashn'Go BIOS
Albany |  |
Darling |  |
Kimberly |  |
MaunaKea |  |
Mt.Ziel |  |
Pitcairn |  |
TU400 |  |
Tasmania |  |


CanGetBitTiming

CanGetBitTiming

Reads the bus timing registers of the CAN controller

Syntax:

BOOL

CanGetBitTiming

(

HANDLE hDevice,

int *nTimingData

)

Parameters:

hDevice
Handle of the CAN device, that is created in the library. Will be returned via ►CanCreateDevice.

nTimingData

Address of an integer array int[2] :

 | IN | OUT
nTimingData[0] | unused | Bus timing register 1
nTimingData[1] | unused | Bus timing register 2

Return values:

If successful, the returned value is non-zero. If errors have occurred, zero will be returned. Informations about the error can be retrieved by a following call of ►CanGetLastError.

Remarks:

The meaning of the registers values is illustrated in the controllers manual.

Requirements:

Windows NT/2000/XP | Version NT 4.0 or later
Windows 95/98/Me | Version 95 or later
Windows CE | Version 3.0 or later
Header: | Declared in gfcanapi.h / gfcanapiCE.h.
Import Library: | gfcan32.lib, gfcan32CE.lib. (for MS Visual C++)

Supported platforms:

= function available [image] = function not available
 | WindowsCE | Flashn'Go BIOS
Albany |  |
Darling |  |
Kimberly |  |
MaunaKea |  |
Mt.Ziel |  |
Pitcairn |  |
TU400 |  |
Tasmania |  |


CanGetLastError

CanGetLastError

Outputs the error code of the last occurred error in driver or library

Syntax:

BOOL

CanGetLastError

(

HANDLE hDevice

)

Parameters:

hDevice
Handle of the CAN device, that is created in the library. Will be returned via ►CanCreateDevice.

Return values:

The return value is the 32-bit error code of the driver or library.

Remarks:

This function should only be used immediately after a function call. The internal error code of the library is only available until the next function call is executed. After a successful function call, the value of this function has no importance.

Requirements:

Windows NT/2000/XP | Version NT 4.0 or later
Windows 95/98/Me | Version 95 or later
Windows CE | Version 3.0 or later
Header: | Declared in gfcanapi.h / gfcanapiCE.h.
Import Library: | gfcan32.lib, gfcan32CE.lib. (for MS Visual C++)

Supported platforms:

= function available [image] = function not available
 | WindowsCE | Flashn'Go BIOS
Albany |  |
Darling |  |
Kimberly |  |
MaunaKea |  |
Mt.Ziel |  |
Pitcairn |  |
TU400 |  |
Tasmania |  |


CanGetStatus

CanGetStatus

Reads all driver-internal status- and error-variables into an integer array

Syntax:

BOOL

CanGetStatus

(

HANDLE hDevice,

int *status

)

Parameters:

hDevice
Handle of the CAN device, that is created in the library. Will be returned via ►CanCreateDevice.

*status

Address of an integer array with the length of int[9]. The driver assigns the following data to this array:

 | SAE81C9x | SJA1000
status[0] | Device error | Driver status
status[1] | Controller status | Controller status
status[2] | Transmit error | Overflow flag: 0 - no overflow occurred 1 - overflow of the software buffer occurred
status[3] | Receive error | arbitration lost capture
status[4] | Monitor active flag | unused
status[5] | Device active flag | unused
status[6] | REC | RX error counter
status[7] | TEC | TX error counter
status[8] | TCEC | error code capture

Return values:

If successful, the returned value is non-zero. If errors have occurred, zero will be returned. Informations about the error can be retrieved by a following call of ►CanGetLastError.

Remarks:

None.

Requirements:

Windows NT/2000/XP | Version NT 4.0 or later
Windows 95/98/Me | Version 95 or later
Windows CE | Version 3.0 or later
Header: | Declared in gfcanapi.h / gfcanapiCE.h.
Import Library: | gfcan32.lib, gfcan32CE.lib. (for MS Visual C++)

Supported platforms:

= function available [image] = function not available
 | WindowsCE | Flashn'Go BIOS
Albany |  |
Darling |  |
Kimberly |  |
MaunaKea |  |
Mt.Ziel |  |
Pitcairn |  |
TU400 |  |
Tasmania |  |


CanReadDescriptor

CanInitMessagePlaceEx

Initializes a message place in the driver. In SJA1000-drivers, an answering-message for a remote frame is initialized with this function.

Syntax:

BOOL

CanInitMessagePlaceEx

(

HANDLE hDevice,

PCAN_MESSAGE_EX msg

)

Parameters:

hDevice
Handle of the CAN device, that is created in the library. Will be returned via ►CanCreateDevice.

msg

Pointer to a ►PCAN_MESSAGE_EX structure. The variables of the structure have to be assigned with the to-be-initialized message before call of this function.

Return values:

If successful, the returned value is non-zero. If errors have occurred, zero will be returned. Informations about the error can be retrieved by a following call of ►CanGetLastError.

Remarks:

In SJA1000-drivers, with this function an answering-message for a remote frame is initialized.

Requirements:

Windows NT/2000/XP | Version NT 4.0 or later
Windows 95/98/Me | Version 95 or later
Windows CE | Version 3.0 or later
Header: | Declared in gfcanapi.h / gfcanapiCE.h.
Import Library: | gfcan32.lib, gfcan32CE.lib. (for MS Visual C++)

Supported platforms:

= function available [image] = function not available
 | WindowsCE | Flashn'Go BIOS
Albany |  |
Darling |  |
Kimberly |  |
MaunaKea |  |
Mt.Ziel |  |
Pitcairn |  |
TU400 |  |
Tasmania |  |


CanReadDescriptorEx

CanReadDescriptor

Reads the descriptor of a messageplace

Syntax:

BOOL

CanReadDescriptor

(

HANDLE hDevice,

USHORT place,

USHORT *descr

)

Parameters:

hDevice
Handle of the CAN device, that is created in the library. Will be returned via ►CanCreateDevice.

place

Number of the messageplace that should be read. Numbers are counted from 0 to 15.

descr

Address of a 16-bit variable, where the desired descriptor is stored into.

Return values:

If successful, the returned value is non-zero. If errors have occurred, zero will be returned. Informations about the error can be retrieved by a following call of ►CanGetLastError.

Remarks:

None.

Requirements:

Windows NT/2000/XP | Version NT 4.0 or later
Windows 95/98/Me | Version 95 or later
Windows CE | Version 3.0 or later
Header: | Declared in gfcanapi.h / gfcanapiCE.h.
Import Library: | gfcan32.lib, gfcan32CE.lib. (for MS Visual C++)

Supported platforms:

= function available [image] = function not available
 | WindowsCE | Flashn'Go BIOS
Albany |  |
Darling |  |
Kimberly |  |
MaunaKea |  |
Mt.Ziel |  |
Pitcairn |  |
TU400 |  |
Tasmania |  |


canreaddescriptorex

CanReadDescriptorEx

Reads the value of a set ID-filter

Syntax:

BOOL

CanReadDescriptorEx

(

HANDLE hDevice,

ULONG place,

ULONG *descr,

ULONG *mask

)

Parameters:

hDevice
Handle of the CAN device, that is created in the library. Will be returned via ►CanCreateDevice.

place

Number of the messageplace that should be read. Numbers are counted from 0 to 15.

descr

Address of a 32-bit variable, where the desired descriptor is stored into.

mask

Address of a 32-bit variable, where the desired mask is stored into.

Return values:

If successful, the returned value is non-zero. If errors have occurred, zero will be returned. Informations about the error can be retrieved by a following call of ►CanGetLastError.

Remarks:

SJA1000 controllers only support one ID-filter. Because of that, the parameter "place" is unused here.

Requirements:

Windows NT/2000/XP | Version NT 4.0 or later
Windows 95/98/Me | Version 95 or later
Windows CE | Version 3.0 or later
Header: | Declared in gfcanapi.h / gfcanapiCE.h.
Import Library: | gfcan32.lib, gfcan32CE.lib. (for MS Visual C++)

Supported platforms:

= function available [image] = function not available
 | WindowsCE | Flashn'Go BIOS
Albany |  |
Darling |  |
Kimberly |  |
MaunaKea |  |
Mt.Ziel |  |
Pitcairn |  |
TU400 |  |
Tasmania |  |


CanReadMessageEx

CanReadMessage

Reads a message out of the receive-buffer of the driver and releases the bufferplace

Syntax:

BOOL

CanReadMessage

(

HANDLE hDevice,

PCAN_MESSAGE *msg

)

Parameters:

hDevice
Handle of the CAN device, that is created in the library. Will be returned via ►CanCreateDevice.

msg

Pointer to a ► CAN_MESSAGE-structure. Into this structure the currently oldest message is read out of the driver.

Return values:

If successful, the returned value is non-zero. If errors have occurred, zero will be returned. Informations about the error can be retrieved by a following call of ►CanGetLastError.

Remarks:

This function should only be used for testing purposes. It does not return to the caller, until a message could been read out of the buffer. During this time the thread of the caller is paused.

For optimum program performance incoming messages should be processed by the callback-mechanism.

Requirements:

Windows NT/2000/XP | Version NT 4.0 or later
Windows 95/98/Me | Version 95 or later
Windows CE | Version 3.0 or later
Header: | Declared in gfcanapi.h / gfcanapiCE.h.
Import Library: | gfcan32.lib, gfcan32CE.lib. (for MS Visual C++)

Supported platforms:

= function available [image] = function not available
 | WindowsCE | Flashn'Go BIOS
Albany |  |
Darling |  |
Kimberly |  |
MaunaKea |  |
Mt.Ziel |  |
Pitcairn |  |
TU400 |  |
Tasmania |  |


CanReadRegister

CanReadMessageEx

Reads a message out of the receive-buffer of the driver and releases the bufferplace

Syntax:

BOOL

CanReadMessageEx

(

HANDLE hDevice,

PCAN_MESSAGE_EXT msg

)

Parameters:

hDevice
Handle of the CAN device, that is created in the library. Will be returned via ►CanCreateDevice.

msg
Pointer to a CAN_MESSAGE_EX structure, where valid data is stored.

Return values:

If successful, the returned value is non-zero. If errors have occurred, zero will be returned. Informations about the error can be retrieved by a following call of ►CanGetLastError.

Remarks:

This function processes messages in a polling-method. If no message is present in the buffer, the function returns with the value CANERR_FRAMETYPE_NOT_AVAILABLE.

For optimum performance, programs should use the callback-mechanism, to process messages.

Requirements:

Windows NT/2000/XP | Version NT 4.0 or later
Windows 95/98/Me | Version 95 or later
Windows CE | Version 3.0 or later
Header: | Declared in gfcanapi.h / gfcanapiCE.h.
Import Library: | gfcan32.lib, gfcan32CE.lib. (for MS Visual C++)

Supported platforms:

= function available [image] = function not available
 | WindowsCE | Flashn'Go BIOS
Albany |  |
Darling |  |
Kimberly |  |
MaunaKea |  |
Mt.Ziel |  |
Pitcairn |  |
TU400 |  |
Tasmania |  |


canreadregister

CanReadRegister

Reads a register of the CAN controller

Syntax:

BOOL

CanReadRegister

(

HANDLE hDevice,

int RegAdr,

int *RegVal

)

Parameters:

hDevice
Handle of the CAN device, that is created in the library. Will be returned via ►CanCreateDevice.

RegAdr

Register address. See controller manual for register addressing

RegVal

Address of an integer variable. Here the driver inscribes the value read from the controller register.

Return values:

If successful, the returned value is non-zero. If errors have occurred, zero will be returned. Informations about the error can be retrieved by a following call of ►CanGetLastError.

Remarks:

This function is designed only for testing purposes. The register-programming of the CAN-controller is not included in this documentation. Therefore the manual of the CAN-controller can be considered.

During normal operations, all accesses to registers are executed by driver and library.

Requirements:

Windows NT/2000/XP | Version NT 4.0 or later
Windows 95/98/Me | Version 95 or later
Windows CE | Version 3.0 or later
Header: | Declared in gfcanapi.h / gfcanapiCE.h.
Import Library: | gfcan32.lib, gfcan32CE.lib. (for MS Visual C++)

Supported platforms:

= function available [image] = function not available
 | WindowsCE | Flashn'Go BIOS
Albany |  |
Darling |  |
Kimberly |  |
MaunaKea |  |
Mt.Ziel |  |
Pitcairn |  |
TU400 |  |
Tasmania |  |


CanSetMonitorMode

CanRegisterCallback

Passes the address of the userdefined callback-function to the library

Syntax:

BOOL

CanRegisterCallback

(

HANDLE hDevice,

void (

_stdcall *Callback

)

(

LPVOID

)

)

Parameters:

hDevice
Handle of the CAN device, that is created in the library. Will be returned via ►CanCreateDevice.

Callback

Address of the user defined ►CanCallback function. Zero deletes the registered callback.

Return values:

If successful, the returned value is non-zero. If errors have occurred, zero will be returned. Informations about the error can be retrieved by a following call of ►CanGetLastError.

Remarks:

This function has to be called once before ►CanStartReceiveQueue with a valid callback-address, so that incoming messages can be processed automatically. An application can use different callback functions in different parts of the program. To change between different callbacks, only a new call with the desired address is required.

To delete the callback address in the library, the function must be called with zero as parameter. This also should be executed before program termination.

Requirements:

Windows NT/2000/XP | Version NT 4.0 or later
Windows 95/98/Me | Version 95 or later
Windows CE | Version 3.0 or later
Header: | Declared in gfcanapi.h / gfcanapiCE.h.
Import Library: | gfcan32.lib, gfcan32CE.lib. (for MS Visual C++)

Supported platforms:

= function available [image] = function not available
 | WindowsCE | Flashn'Go BIOS
Albany |  |
Darling |  |
Kimberly |  |
MaunaKea |  |
Mt.Ziel |  |
Pitcairn |  |
TU400 |  |
Tasmania |  |


CanSetBitTiming

CanReset

Resets the CAN-controller and the driver to the default settings. The last used baudrate is kept and all buffers are flushed.

Syntax:

BOOL

CanReset

(

HANDLE hDevice,

int *data

)

Parameters:

hDevice
Handle of the CAN device, that is created in the library. Will be returned via ►CanCreateDevice.

data

Address of an integer array int[2]. The reset-status is registered in this array by the driver as follows:

data[0] Device Error
data[1] Controller Status

Return values:

If successful, the returned value is non-zero. If errors have occurred, zero will be returned. Informations about the error can be retrieved by a following call of ►CanGetLastError.

Remarks:

CanReset is executed during start of the driver and after ►CanSetBaudrate. In user applications this function is required to reset drivers and bus to a defined state after exceptions or other profoundly errors.

All buffers are flushed and messages in buffers get lost. The last used baudrate and monitoring mode are untouched by this reset. After booting of the system a baudrate of 125kbaud is set and monitoring mode is activated.

Requirements:

Windows NT/2000/XP | Version NT 4.0 or later
Windows 95/98/Me | Version 95 or later
Windows CE | Version 3.0 or later
Header: | Declared in gfcanapi.h / gfcanapiCE.h.
Import Library: | gfcan32.lib, gfcan32CE.lib. (for MS Visual C++)

Supported platforms:

= function available [image] = function not available
 | WindowsCE | Flashn'Go BIOS
Albany |  |
Darling |  |
Kimberly |  |
MaunaKea |  |
Mt.Ziel |  |
Pitcairn |  |
TU400 |  |
Tasmania |  |


CanSetBaudrate

CanSetBaudrate

Sets a new baudrate in the controller

Syntax:

BOOL

CanSetBaudrate

(

HANDLE hDevice,

int *baud

)

Parameters:

hDevice
Handle of the CAN device, that is created in the library. Will be returned via ►CanCreateDevice.

baud

Address of an integer array int[2]:

baud[0] new Baudrate in kBaud Device error
baud[1] unused Controller status

Return values:

If successful, the returned value is non-zero. If errors have occurred, zero will be returned. Informations about the error can be retrieved by a following call of ►CanGetLastError.

Remarks:

Valid values for the baudrate are 10, 20, 50, 100, 125, 250, 500, 800 and 1000kBaud. All different values will result in the default value of 125kBaud.

If -1 is passed to, the library offers a modal dialog for choosing the baudrate. This dialog is not supported under Windows CE!

Requirements:

Windows NT/2000/XP | Version NT 4.0 or later
Windows 95/98/Me | Version 95 or later
Windows CE | Version 3.0 or later
Header: | Declared in gfcanapi.h, gfcanapiCE.h
Import Library: | gfcan32.lib, gfcan32CE.lib (for MS Visual C++)

Supported platforms:

= function available [image] = function not available
 | WindowsCE | Flashn'Go BIOS
Albany |  |
Darling |  |
Kimberly |  |
MaunaKea |  |
Mt.Ziel |  |
Pitcairn |  |
TU400 |  |
Tasmania |  |


CanSetBitTiming

CanSetBitTiming

Defines the individual bit-timing on the CAN-bus.

Syntax:

BOOL

CanSetBitTiming

(

HANDLE hDevice,

int *nTimingData

)

Parameters:

hDevice
Handle of the CAN device, that is created in the library. Will be returned via ►CanCreateDevice.

nTimingData

Address of an integer array int[5]:

 | IN | OUT
nTimingData[0] | Synchronisation Jump Width | unused
nTimingData[1] | Baudrate Prescaler | unused
nTimingData[2] | Time Segment 1 | unused
nTimingData[3] | Time Segment 2 | unused
nTimingData[4] | Triple Sampling | unused

Return values:

If successful, the returned value is non-zero. If errors have occurred, zero will be returned. Informations about the error can be retrieved by a following call of ►CanGetLastError.

Remarks:

For additional informations about the single meanings of the values, see the CAN-controllers manual.

Settings of the bit-timing are persistent and kept over on a reset. Changes take effect by calling this function with different values or calling the function ►CanSetBaudrate.

Requirements:

Windows NT/2000/XP | Version NT 4.0 or later
Windows 95/98/Me | Version 95 or later
Windows CE | Version 3.0 or later
Header: | Declared in gfcanapi.h, gfcanapiCE.h
Import Library: | gfcan32.lib, gfcan32CE.lib (for MS Visual C++)

Supported platforms:

= function available [image] = function not available
 | WindowsCE | Flashn'Go BIOS
Albany |  |
Darling |  |
Kimberly |  |
MaunaKea |  |
Mt.Ziel |  |
Pitcairn |  |
TU400 |  |
Tasmania |  |


CanStartReceiveQueue

CanSetMonitorMode

Turns the monitoring mode of the controller on or off

Syntax:

BOOL

CanSetMonitorMode

(

HANDLE hDevice,

int Mode

)

Parameters:

hDevice
Handle of the CAN device, that is created in the library. Will be returned via ►CanCreateDevice.

Mode

A value = 0 turns the monitoring mode off. Any other value switches the monitoring mode on.

Remark: Monitoring mode is only available on the SAE81C9x controllers.

Return values:

If successful, the returned value is non-zero. If errors have occurred, zero will be returned. Informations about the error can be retrieved by a following call of ►CanGetLastError.

Remarks:

In monitoring mode, all incoming messages, that are unassigned to any message place, are received on message place 0. Message place 0 can not be used for normal receiving of messages, an assigned descriptor to this message place will be ignored.

Monitoring mode is only supported on the SAE 81C9x-series controllers.

Requirements:

Windows NT/2000/XP | Version NT 4.0 or later
Windows 95/98/Me | Version 95 or later
Windows CE | Version 3.0 or later
Header: | Declared in gfcanapi.h, gfcanapiCE.h
Import Library: | gfcan32.lib, gfcan32CE.lib (for MS Visual C++)

Supported platforms:

= function available [image] = function not available
 | WindowsCE | Flashn'Go BIOS
Albany |  |
Darling |  |
Kimberly |  |
MaunaKea |  |
Mt.Ziel |  |
Pitcairn |  |
TU400 |  |
Tasmania |  |


CanStartReceiveQueue

CanStartReceiveQueue

Activates background-processing of incoming messages

Syntax:

BOOL

CanStartReceiveQueue

(

HANDLE hDevice,

int nPriority

)

Parameters:

hDevice
Handle of the CAN device, that is created in the library. Will be returned via ►CanCreateDevice.

nPriority

Integer value of the priority level, that is assigned to the background-process. Valid are all values used for the Win32-API-function SetThreadPriority().

This value can not be set to a value lower than 103!

Return values:

If successful, the returned value is non-zero. If errors have occurred, zero will be returned. Informations about the error can be retrieved by a following call of ►CanGetLastError.

Remarks:

The processing of messages is running in a parallel thread, independent from all other duties of the application. Because of that, the application doesn't need to poll the message buffer nor it has to wait for messages in any other kind and thus it is always operational.

The function is called once at application start, if a baudrate is set and a callback is registered. Under Windows CE the extended priority-management of version 3.0 is not implemented yet. Only the Win32 compatible method, known from earlier versions, is supported at the moment.

Requirements:

Windows NT/2000/XP | Version NT 4.0 or later
Windows 95/98/Me | Version 95 or later
Windows CE | Version 3.0 or later
Header: | Declared in gfcanapi.h, gfcanapiCE.h
Import Library: | gfcan32.lib, gfcan32CE.lib (for MS Visual C++)

Supported platforms:

= function available [image] = function not available
 | WindowsCE | Flashn'Go BIOS
Albany |  |
Darling |  |
Kimberly |  |
MaunaKea |  |
Mt.Ziel |  |
Pitcairn |  |
TU400 |  |
Tasmania |  |


CanTransmitMessageEx

CanStopReceiveQueue

Stops the background processing thread for incoming messages

Syntax:

BOOL

CanStopReceiveQueue

(

HANDLE hDevice,

)

Parameters:

hDevice
Handle of the CAN device, that is created in the library. Will be returned via ►CanCreateDevice.

Return values:

If successful, the returned value is non-zero. If errors have occurred, zero will be returned. Informations about the error can be retrieved by a following call of ►CanGetLastError.

Remarks:

This function deactivates the prior created additional thread for processing incoming messages. This function will be called at termination of an application before the CAN-port is closed.

Requirements:

Windows NT/2000/XP | Version NT 4.0 or later
Windows 95/98/Me | Version 95 or later
Windows CE | Version 3.0 or later
Header: | Declared in gfcanapi.h, gfcanapiCE.h
Import Library: | gfcan32.lib, gfcan32CE.lib (for MS Visual C++)

Supported platforms:

= function available [image] = function not available
 | WindowsCE | Flashn'Go BIOS
Albany |  |
Darling |  |
Kimberly |  |
MaunaKea |  |
Mt.Ziel |  |
Pitcairn |  |
TU400 |  |
Tasmania |  |


CanTransmitMessage

CanTransmitMessage

Transmits a message on the CAN-bus

Syntax:

BOOL

CanTransmitMessage

(

HANDLE hDevice,

PCAN_MESSAGE msg

)

Parameters:

hDevice
Handle of the CAN device, that is created in the library. Will be returned via ►CanCreateDevice.

msg

Pointer to a ► CAN_MESSAGE-structure. Into this structure the currently oldest message is read out of the driver.

Return values:

If successful, the returned value is non-zero. If errors have occurred, zero will be returned. Informations about the error can be retrieved by a following call of ►CanGetLastError.

Remarks:

None.

Requirements:

Windows NT/2000/XP | Version NT 4.0 or later
Windows 95/98/Me | Version 95 or later
Windows CE | Version 3.0 or later
Header: | Declared in gfcanapi.h, gfcanapiCE.h
Import Library: | gfcan32.lib, gfcan32CE.lib (for MS Visual C++)

Supported platforms:

= function available [image] = function not available
 | WindowsCE | Flashn'Go BIOS
Albany |  |
Darling |  |
Kimberly |  |
MaunaKea |  |
Mt.Ziel |  |
Pitcairn |  |
TU400 |  |
Tasmania |  |


CanTransmitMessageEx

CanTransmitMessageEx

Transmits a message on the CAN-bus

Syntax:

BOOL

CanTransmitMessageEx

(

HANDLE hDevice,

PCAN_MESSAGE_EX msg

)

Parameters:

hDevice
Handle of the CAN device, that is created in the library. Will be returned via ►CanCreateDevice.

msg

Pointer to a ► CAN_MESSAGE-structure. Into this structure the currently oldest message is read out of the driver.

Return values:

If successful, the returned value is non-zero. If errors have occurred, zero will be returned. Informations about the error can be retrieved by a following call of ►CanGetLastError.

Remarks:

None.

Requirements:

Windows NT/2000/XP | Version NT 4.0 or later
Windows 95/98/Me | Version 95 or later
Windows CE | Version 3.0 or later
Header: | Declared in gfcanapi.h, gfcanapiCE.h
Import Library: | gfcan32.lib, gfcan32CE.lib (for MS Visual C++)

Supported platforms:

= function available [image] = function not available
 | WindowsCE | Flashn'Go BIOS
Albany |  |
Darling |  |
Kimberly |  |
MaunaKea |  |
Mt.Ziel |  |
Pitcairn |  |
TU400 |  |
Tasmania |  |


CanWriteDescriptor

CanWriteDescriptor

Initialize a message place with a descriptor

Syntax:

BOOL

CanWriteDescriptor

(

HANDLE hDevice,

USHORT place,

USHORT *descr

)

Parameters:

hDevice
Handle of the CAN device, that is created in the library. Will be returned via ►CanCreateDevice.

place

Number of the messageplace that should be read. Numbers are counted from 0 to 15.

descr

Address of a 16-bit variable, where the desired descriptor is stored into.

Return values:

If successful, the returned value is non-zero. If errors have occurred, zero will be returned. Informations about the error can be retrieved by a following call of ►CanGetLastError.

Remarks:

None.

Requirements:

Windows NT/2000/XP | Version NT 4.0 or later
Windows 95/98/Me | Version 95 or later
Windows CE | Version 3.0 or later
Header: | Declared in gfcanapi.h, gfcanapiCE.h
Import Library: | gfcan32.lib, gfcan32CE.lib (for MS Visual C++)

Supported platforms:

= function available [image] = function not available
 | WindowsCE | Flashn'Go BIOS
Albany |  |
Darling |  |
Kimberly |  |
MaunaKea |  |
Mt.Ziel |  |
Pitcairn |  |
TU400 |  |
Tasmania |  |


CanWriteDescriptorEx

CanWriteDescriptorEx

Placeholder in a userdefined callback-function for event-controlled message receiving

Syntax:

BOOL

CanWriteDescriptorEx

(

HANDLE hDevice,

ULONG place,

ULONG *descr,

ULONG *mask

)

Parameters:

hDevice
Handle of the CAN device, that is created in the library. Will be returned via ►CanCreateDevice.

place

Number of the messageplace that should be read. Numbers are counted from 0 to 15.

descr

Address of a 32-bit variable, where the desired descriptor is stored into.

mask

Address of a 32-bit variable, where the desired mask is stored into.

Return values:

If successful, the returned value is non-zero. If errors have occurred, zero will be returned. Informations about the error can be retrieved by a following call of ►CanGetLastError.

Remarks:

None.

Requirements:

Windows NT/2000/XP | Version NT 4.0 or later
Windows 95/98/Me | Version 95 or later
Windows CE | Version 3.0 or later
Header: | Declared in gfcanapi.h, gfcanapiCE.h
Import Library: | gfcan32.lib, gfcan32CE.lib (for MS Visual C++)

Supported platforms:

= function available [image] = function not available
 | WindowsCE | Flashn'Go BIOS
Albany |  |
Darling |  |
Kimberly |  |
MaunaKea |  |
Mt.Ziel |  |
Pitcairn |  |
TU400 |  |
Tasmania |  |


CanWriteRegister

CanWriteRegister

Determines the baudrate of the driver and returns it as kbaud-value

Syntax:

BOOL

CanWriteRegister

(

HANDLE hDevice,

int RegAdr,

int RegVal

)

Parameters:

hDevice
Handle of the CAN device, that is created in the library. Will be returned via ►CanCreateDevice.

RegAddr

Address of the register that is to be new set. The addressing of registers is described in the manual of the controller. The advises there are to be considered.

RegVal

Value to be written into the register. Considered is only the LSB of this integer value.

Return values:

If successful, the returned value is non-zero. If errors have occurred, zero will be returned. Informations about the error can be retrieved by a following call of ►CanGetLastError.

Remarks:

This function is designed for testing purposes only and should be used with great care, because wrong write accesses to the controller register may harm the function of the driver.

In any case, before manipulating single registers, the manual of the controller has to be considered in detail, to understand the register-model of the controller and its functionality.

Requirements:

Windows NT/2000/XP | Version NT 4.0 or later
Windows 95/98/Me | Version 95 or later
Windows CE | Version 3.0 or later
Header: | Declared in gfcanapi.h, gfcanapiCE.h
Import Library: | gfcan32.lib, gfcan32CE.lib (for MS Visual C++)

Supported platforms:

= function available [image] = function not available
 | WindowsCE | Flashn'Go BIOS
Albany |  |
Darling |  |
Kimberly |  |
MaunaKea |  |
Mt.Ziel |  |
Pitcairn |  |
TU400 |  |
Tasmania |  |


CAN_MESSAGE_EX

CAN_MESSAGE

This structure is used by the functions in transmission and receiving messages to gain all parts of the message at once.

typedef struct _CAN_MESSAGE

{
USHORT descr;
USHORT place;
USHORT time_stamp;
USHORT reserved;
UCHAR data[8];
}

CAN_MESSAGE,

*PCAN_MESSAGE;

Structure

descr

Descriptor of the message. Contains identifier, remote-frame flag (RTR) and message-lenght in bytes (DLC)

place

Number of the message place, the message was sent through, respectively the message was received through.

time_stamp

Timestamp of the received message. Is only valid for receiving messages on the places 0 .. 7; for 8 .. 15 no timestamp is given. Consider the manual of the controller for further informations. This value is only used for receiving messages, not for sending.

reserved

Reserved value.

data[8]

Databytes of the message. It is always only the number of bytes is valid, that is defined as lenght in DLC. All other bytes are undefined.


CAN_MESSAGE_EX

CAN_MESSAGE_EX

This structure is used by the functions with the extension "*Ex" in transmission and receiving messages to gain all parts of the message at once.

typedef struct _CAN_MESSAGE_EX

{
int frametype;
UINT id;
BOOL rtr;
USHORT length;
USHORT place;
ULONG time_stamp;
ULONG ErrorStatus;
UCHAR data[8];
 }

CAN_MESSAGE_EX,
*PCAN_MESSAGE_EX;

Structure

frametype

This structure supports messages with 11- and 29-bit identifier and can take the value STANDARD or EXTENDED.

id

Identifier of the message. Can be 11 or 29 bits long.

rtr

Remote frame flag. If true, this value, it is a remote frame. Detailed informations about remote frames can be found in the respective controller manual.

length

Message-lenght in bytes

place

Number of the message place, a message has been sent or received through. Only the SAE 819Cx-series controller support message places. This value is unused with other controllers.

time_stamp

Time stamp of the received message. The time stamp at SAE 819Cx-controllers is only valid on the places 0 to 7. On the places 8 to 15 no time stamp is given. Further informations can be taken from the controllers manual.

SJA1000 controllers do not support time stamps. Time stamps are unused for sending messages.

ErrorStatus

This status is unused for sending messages.

If the value is non-zero during receiving a message, it is the errorcode of the driver and the type is an error frame, that was generated and sent to the message buffer by the driver due to occurred errors. The data lenght is 5 bytes and the meaning of the byte can be taken from the below table:

data[0] | Status register of the controller
data[1] | Error code capture
data[2] | Arbitration lost capture
data[3] | Rx error counter
data[4] | Tx error counter

Type of this message is STANDARD. Error frames are only supported by drivers for the SJA1000 controllers.

data[8]

Databytes of the message. There are always as many bytes valid in this array, as has been given as lenght. All other bytes are undefined.


Error codes

Error codes

All error codes are defined as constant values and deposited in the headerfile canerror.h. By including this file into a project, the following definitions are available. The driver and the library are using these codes to notify the user about success or fail of a function call.

The return value of CanGetLastError() is always one of the following values, respectively the standard error code of the operating system.

CANERR_STATUS_OK | No error
CANERR_DRIVER_NOT_PRESENT | Driver not loaded
CANERR_CANNOT_CREATE_DEVICE | Unable to create device
CANERR_DEVICE_RESSOURCES | Unable to load driver
CANERR_NO_RESSOURCES | Driver settings not found
CANERR_RESOURCE_CONFLICT | Driver settings already in use-
CANERR_FUNCTION_NOT_IMPLEMENTED | Erroneous access code or function not implemented.
CANERR_INVALID_PARAMETER | Invalid parameter within function call
CANERR_HARDWARE_FAILURE | Erroneous or not present hardware
CAN_E_RWARNING | 96 <= REC < 128
CAN_E_RPASSIVE | REC >= 128
CAN_E_TWARNING | 96 <= TEC < 128
CAN_E_TPASSIVE | TEC >= 128
CAN_E_TCHECK | TCEC >= 4
CAN_E_BUSOFF | Bus Off
CAN_DRV_E_ACTIV | Driver already active
CAN_DRV_E_NACTIV | Driver not active
CAN_DRV_E_NOT_FF | No 0xFF read
CAN_DRV_E_PORT_IO | Error in port-I/O
CAN_DRV_E_MEM_IO | Error in memory-I/O
CAN_DRV_E_BUS_OFF | Bus off
CAN_DRV_E_PL_ACTIV | Messageplace is already active
CAN_DRV_E_PL_NACTIV | Messageplace is not active
CAN_DRV_E_TRA_FULL | Transceive-buffer is full / still sending
CAN_DRV_E_REC_FULL | Receive-buffer is full / still receiving
CAN_DRV_E_REM_FULL | Remote receive-buffer is full
CAN_DRV_E_REC_EMPTY | Receive-buffer is empty
CAN_DRV_E_REM_EMPTY | Remote receive-buffer is empty
CAN_DRV_E_BUFF_TYP | Wrong buffer type
CAN_DRV_E_MON_ON | Place 0 in monitor-mode
CAN_DRV_E_MON_OFF | Monitor-mode off
CAN_DRV_E_PL0_ACTIV | Place 0 is active
CAN_DRV_E_NTSTAMP | No timestamp on this place
CAN_DRV_E_REC_INT | No receive-INTs allowed
CAN_DRV_E_NO_INT | No INT(s) triggered.


Template

Function name

Short description of the function

Syntax:

DWORD (12pt bold)

blabla

(

param-name,

param-name2

)

Parameters:

param-name
description of parameter, values

param-name2
description of parameter, values

Return values:

returned values

Remarks:

remarks, hints

Requirements:

BIOS: | Version 3.5 or later
WindowsCE: | Version 3.0 or later
Header: | GFSystemApi.h, FlashngoCE.h
Import Library: | GFSystem.lib

Supported platforms:

= function available [image] = function not available
 | WindowsCE | Flashn'Go BIOS
Albany |  |
Darling |  |
Kimberly |  |
MaunaKea |  |
Mt.Ziel |  |
Pitcairn |  |
TU400 |  |
Tasmania |  |