IXXAT LIN2CAN, Api Manual, Page: 6 / 31

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.