IXXAT LIN2CAN User manual

LIN2CAN API (L2CAPI)
MANUAL
ENGLISH

HMS Technology Center Ravensburg GmbH
Helmut-Vetter-Straße 2
88213 Ravensburg
Germany
Tel.: [phone]
Fax: [phone]
Internet: www.hms-networks.de
E-Mail: [e-mail]
Support
For problems or support with this product or other HMS products please
request support at www.ixxat.com/support.
Further international support contacts can be found on our webpage
www.ixxat.com
Copyright
Duplication (copying, printing, microfilm or other forms) and the electronic
distribution of this document is only allowed with explicit permission of HMS
Technology Center Ravensburg GmbH. HMS Technology Center
Ravensburg GmbH reserves the right to change technical data without
prior announcement. The general business conditions and the regulations
of the license agreement do apply. All rights are reserved.
Registered trademarks
All trademarks mentioned in this document and where applicable third
party registered are absolutely subject to the conditions of each valid label
right and the rights
of particular registered proprietor. The absence of
identification of a trademark does not automatically mean that it is not
protected by trademark law.
Document number: 4.01.0130.20100
Version: 1.6

Content
3
L2C-API Manual, Version 1.6
1Introduction....................................................................................5
2LIN-CAN-RS232 Gateway API (L2CAPI)........................................6
2.1 Basic structure........................................................................6
2.2 Creating the API object...........................................................6
2.3Overview of interfaces............................................................7
2.4 Interface IUnknown.................................................................8
2.5 Interface ILIN2CAN_API_Ctrl .................................................9
2.6 Interface ILIN2CAN_GeneralConfig2...................................10
2.7 Interface ILIN2CAN_GatewayConfig2..................................12
2.8 Interface ILIN2CAN_SlaveConfig.........................................14
2.9 Interface ILIN2CAN_MasterConfig2.....................................15
2.10Interface ILIN2CAN_LINMsgQueue2....................................16
2.10.1 Error overview ......................................................................17
2.11Interface ILIN2CAN_Master_Slave2.....................................18
2.12Overview: Permitted API calls / operation mode................19
2.13Brief overview of API............................................................20
2.13.1 Interface: ILIN2CAN_GeneralConfig2..................................20
2.13.2 Interface: ILIN2CAN_GatewayConfig2.................................22
2.13.3 Interface: ILIN2CAN_SlaveConfig........................................23
2.13.4 Interface: ILIN2CAN_MasterConfig2....................................23
2.13.5 Interface: ILIN2CAN_LINMsgQueue2..................................24
2.13.6 Interface: ILIN2CAN_Master_Slave2 ...................................25
2.13.7 Data type definitions.............................................................26

Introduction
5
L2C-API Manual, Version 1.6
1 Introduction
The LIN2CAN Gateway API (in short: L2CAPI) serves as an interface for the
configuration and controlling of the LIN2CAN Gateway hardware and for the
access to the LIN message traffic. All functions of the LIN2CAN device can be
used in own programs with the LIN2CAN gateway API. Specific test applications
or PC based network simulations can be realized. (For further information read
the LIN2CAN Gateway manual.) The LIN2CAN device with the L2CAPI can be
used as a developer platform. The functions are divided into function groups
according to type of function or operation mode.

LIN-CAN-RS232 Gateway API (L2CAPI)
6
L2C-API Manual, Version 1.6
2 LIN-CAN-RS232 Gateway API (L2CAPI)
2.1 Basic structure
The structure of the API is similar to that of a COM object. The API is sub-divided
into interfaces and has a reference counter used for releasing the API. If an
interface is requested, the counter is increased by one. If an interface is no
longer required, it must be released with
Release
. If the counter reaches 0, the
L2CAPI object is deleted. Each interface is derived from the interface
IUnknown
.
This interface contains the methods
QueryInterface
,
AddRef
and
Release
.
Every method of the API (except
AddRef
and
Release
) returns an
HRESULT
value
as an error code.
S_OK (0)
stands for success.
2.2 Creating the API object
The following files are required to be able to work with the API:
•L2CAPI.lib
•L2CAPI.dll
•L2CAPI.hpp
The LIB file must be integrated in the program to be created. It loads the DLL
file when the program is started. The methods of the API are defined in the HPP
file.
In addition, the line
#define INITGUID
must be contained in a CPP file of the
project. This serves to provide memory space for the GUIDs (Global Unique
Identifiers). Every interface of the API has one of these 128-bit IDs for
unambiguous definition.
First the API object must be created with
L2CAPI_CreateInstance()
. The hand-off
parameters are the ID for the required interface and a pointer for the required
interface. The call is as follows:
HRESULT hResult = E_FAIL;
IUnknown* pIUnknown = NULL;
hResult = L2CAPI_CreateInstance(IID_IUnknown, (void**)&pIUnknown);
If successful, every other interface of the API can now be called with this
interface pointer. If unsuccessful, the error code can be converted into a
readable string by calling
L2CAPI_FormatError()
. If the interface is no longer
required, it is released again by the following call.
if(pIUnknown != NULL)
{
pIUnknown->Release();
pIUnknown = NULL;
}
A project example (L2CAPI_CONSOLE_APP) and a project template
(L2CAPI_App- Template) is included for the easier beginning to implement an
own application.

LIN-CAN-RS232 Gateway API (L2CAPI)
7
L2C-API Manual, Version 1.6
2.3 Overview of interfaces
The API implements the following interfaces:
•ILIN2CAN_API_Ctrl
Serves to connect the API with the device or to disconnect the
connection and query the connection status.
•ILIN2CAN_GeneralConfig2
Serves to query or make the basic settings of the device such as
name, LIN baud rate and startup operation.
•ILIN2CAN_GatewayConfig2
Serves to make the settings that are required for the gateway mode.
These include the CAN baud rate and the CAN transceiver mode and
the translation table for translating LIN to CAN objects and vice versa.
•ILIN2CAN_SlaveConfig
Defines the response to a LIN identifier.
•ILIN2CAN_MasterConfig2
Defines the schedule table for the master operation mode.
•ILIN2CAN_LINMsgQueue2
Serves to read out messages from the LIN message queue and query
their status.
•ILIN2CAN_Master_Slave2
With this interface it is possible to place LIN IDs and LIN objects on
the LIN bus by PC call and to connect a wakeup signal to the BUS.
The methods of the interfaces can only be called if the device is either in
L2C_OP_MODE_SLAVE_PC or L2C_OP_MODE_MASTER_PC mode!

LIN-CAN-RS232 Gateway API (L2CAPI)
8
L2C-API Manual, Version 1.6
2.4 Interface IUnknown
The interface provides the following methods:
•HRESULT QueryInterface([in] REFIID riid, [out] LPVOID *ppvObj)
With QueryInterface, one of the interfaces listed in 2.3 can be
queried. The call is the same as for L2CAPI_CreateInstance, the only
difference being that here no new instance of the class is created, but
a pointer of the required interfaces is returned. By calling
QueryInterface, the reference counter is automatically increased by
one.
•ULONG AddRef()
AddRef increases the reference counter of the object by one. The
return value is the new status of the reference counter. This method
must be called if an interface pointer itself is cloned.
•ULONG Release()
With Release, an interface that is no longer required is released
again. The new reference counter status is returned.

LIN-CAN-RS232 Gateway API (L2CAPI)
9
L2C-API Manual, Version 1.6
2.5 Interface ILIN2CAN_API_Ctrl
This interface provides the following methods:
•Connect([in] PCHAR pszName, [in] PCHAR pszMode)
With Connect the API is connected to the device by the stated
interface. The name of the interface to be used is given in pszName
e.g. “COM1” or “COM2”. In pszMode, “baud=115200 parity=N data=8
stop=1” must always be transmitted. If the connection was made
successfully, S_OK is returned, otherwise an error code that can be
converted into a readable string with L2CAPI_FormatError().
•Disconnect()
With Disconnect the connection to the device is disconnected again.
•IsConnected()
IsConnected is used to query whether the device is still connected.
This function checks the status of the DSR line. In this way
disconnection of the device can also be detected during operation.

LIN-CAN-RS232 Gateway API (L2CAPI)
10
L2C-API Manual, Version 1.6
2.6 Interface ILIN2CAN_GeneralConfig2
This interface implements the following methods:
•GetDeviceName([out] PSTRING psDeviceName)
•SetDeviceName([in] PSTRING psDeviceName)
Get/SetDeviceName serves to give the device a name. 16 characters
are permitted including “\0”.
• GetVersionInformation([out] PL2C_VersionInformation pVersionInfo);
GetVersionInformation queries the version information of the device.
The structure is as follows:
struct
{
char strFirmwareVersion[8];
char strHardwareVersion[8];
}L2C_VersionInformation, *PL2C_VersionInformation;
Each string is terminated with 0.
•GetLINBaudrate([out] PWORD pwBaudrate);
•SetLINBaudrate([in] WORD wBaudrate);
Get/SetLINBaudrate defines the baud rate of the LIN bus. The
following values are possible: 2400, 9600 and 19200 bauds.
• GetOperationMode([out] PL2C_OperationMode pnOperationMode);
• SetOperationMode([in] L2C_OperationMode nOperationMode);
Define the current operation mode of the device. The following modes
are possible:
L2C_OP_MODE_SLAVE_PC
L2C_OP_MODE_MASTER_PC
• GetStartUpOpMode([out] PL2C_OperationMode pnOperationMode);
•SetStartUpOpMode ([in] L2C_OperationMode nOperationMode);
These functions define the startup behavior of the device if the serial
cable is not connected to the PC. The following startup operation
modes are permitted:
L2C_OP_MODE_SLAVE
L2C_OP_MODE_MASTER
L2C_OP_MODE_GATEWAY_SLAVE
L2C_OP_MODE_GATEWAY_MASTER
•GetStandbyTime([out] PWORD pwStandbyTime);
•SetStandbyTime([in] WORD wStandbyTime);
Here it is possible to define after how much time (in seconds) without
bus traffic the device switches to standby mode (LIN and CAN). If the
device is connected to the PC, it always remains “awake”. If the value
0xFFFF is transmitted, the device never goes into standby mode.