D pduapi user-manual

D-PDU API Software for
Vehicle Communication Interfaces
User Manual
Version 3.6, June 2013
SOFTING Automotive Electronics GmbH
Richard-Reitzner-Allee 6
85540 Haar, Germany
Tel: +49 (0) 89 4 56 56 - 420
Fax: +49 (0) 89 4 56 56 - 399
info.automotive@softing.com
www.softing.com

© 2013 SOFTING Automotive Electronics GmbH
No part of these instructions may be reproduced (printed material, photocopies, microfilm or other method) or
processed, copied or distributed using electronic systems in any form whatsoever without prior written permission by
SOFTING Automotive Electronics GmbH. Any violations will lead to compensation claims.
All rights reserved, in particular in the event that a patent is granted or that a utility model or a design is registered.
The producer reserves the right to make changes to the scope of supply as well as changes to technical data, even
without prior notice.
Careful attention was given to the quality and functional integrity in designing, manufacturing and testing the system.
However, no liability can be assumed for potential errors or for their effects, especially in terms of suitability of the
system for a specific application. Should you find errors, please inform your distributor of the nature of these errors and
the circumstances under which they occur. We will be responsive to all reasonable ideas and will follow up on them,
taking measures to improve the product, if necessary.
All rights reserved.

Contents
Preface I
Disclaimer II
1 1 Introduction
1.1 1 Modular vehicle communication interface concept and D-PDU API
1.2 4 D-PDU API products from Softing
1.2.1 4 D-PDU API software for vehicle communication interfaces
1.2.2 5 Diagnostic Tool Set with D-PDU API support
1.3 6 Documentation
1.3.1 6 Related standards
1.3.2 6 Further documents
2 7 System requirements
2.1 7 Hardware
2.2 7 Software
2.3 8 Licensing
3 9 Scope of delivery
3.1 9 System components
3.2 9 Configuration files
3.3 9 Applications
4 10 Installation
4.1 10 Software installation
4.2 10 Hardware installation
4.3 10 Test your installation
5 11 Uninstall
6 12 Integration of the D-PDU API
6.1 12 General information
6.2 13 D-PDU API system topologies
6.3 15 D-PDU API functionality
6.3.1 16 ComLogicalLinks
6.3.2 17 Communication protocols
6.3.3 18 ComParameters
6.3.4 19 ComPrimitives
6.4 20 D-PDU API tool integration

6.5 21 D-PDU API migration support
7 22 API reference
7.1 22 API functions
7.1.1 22 Overview
7.1.2 23 General usage
7.1.3 28 Details
7.2 81 IOCTL commands
7.2.1 81 Overview
7.2.2 82 Details
7.3 99 Data types and structures
7.4 99 Limitations
8 101 ComParameter reference
9 102 Demo and test application
9.1 102 Demo application
9.2 103 Interactive test application
10 112 D-PDU API Configuration Manager
11 114 D-PDU API Demonstrator
12 115 Appendix
12.1 115 Error codes
12.2 116 Troubleshooting
12.3 117 Trace mechanism
12.4 117 Support and maintenance
12.5 118 Additional services
12.6 118 RDF file
13 119 References and Index
13.1 119 References
13.2 120 Index of figures
13.3 121 Index of tables

Preface
This documentation provides essential information on the D-PDU API software for
vehicle communication interfaces from Softing. The following chapters cover:
• Short introduction to the MVCI concept and the D-PDU API
• System requirements and installation procedure
• Description of demo- and test applications
• Reference of D-PDU API functions, elements and ComParameters
• Reference of related documents
Preface I

Disclaimer
Warning!
Using this product can be dangerous.
Please use it with care.
This software allows you to control and influence electronic communication systems
in a vehicle. Thus your actions and applications can cause severe personal damages
or damages to property. Therefore only persons may use this software
who have completely understood the possible consequences of their
actions with this software or
who have been trained especially to use this software
Particularly using this software in a moving vehicle is only permitted for especially
trained persons.
In case of other persons using this software, Softing Automotive Electronics
GmbH hereby expressly gives notice that Softing’s warranty shall be limited to
the correction of defects, and Softing Automotive Electronics GmbH hereby
expressly disclaims any liability over and above the refunding of the price paid
for this software.
Disclaimer II

1 Introduction
1.1 Modular vehicle communication interface concept and D-PDU API
The Modular vehicle communication interface (MVCI) project was initiated by several
OEMs in 2001. The main objective is to achieve exchangeability of components in vehicle
communication systems and thus have the ability to optimize systems in terms of
functionality and costs.
The main use cases seen in the MVCI project are:
OEM-mergers
OEM cross vehicle platform ECUs
General applications with ODX (e.g. service testers, etc.)
OEM franchised dealer and aftermarket service outlet diagnostic tools
The MVCI concept defines general requirements for VCI hardware, API software and
diagnostic MCD 3D server applications. To allow exchangeability of vehicle interfaces
three compliance levels are defined (software compliance, electrical compliance and
mechanical compliance).
After some preparatory work in small working groups the official standardization work in
ISO started in 2004. The standardization activities are lead by task forces of ISO TC22
SC3 WG1. Since the MVCI standard is deeply related to ODX the standardization work of
both standards was executed in joint activities in parallel with a close cooperation between
ASAM and ISO. Below the task forces and ISO standard documents are listed:
ISO TC22 SC3 WG1 TF10: MVCI – ISO 22900
o ISO 22900-1 (DIS) Road vehicles -- Modular vehicle communication
interface (MVCI) - Part 1: Hardware design requirements
interface (MVCI) - Part 2: D-PDU API (Diagnostic Protocol Data Unit
Application Programmer Interface)
interface (MVCI) - Part 3: Server API (Application Programmer Interface)
ISO TC22 SC3 WG1 TF11: ODX – ISO 22901
o ISO 22901-1 (DIS) Road vehicles - Open diagnostic data exchange
(ODX) - Part 1: Data model specification
Softing actively contributes to MVCI and ODX standardization since 2002.
1

In Figure 1 the structure of a MVCI system is depicted. It shows the system components
and corresponding ISO standards.
Figure 1: MVCI system structure
In MVCI systems ODX data files are a central element (see Figure 2). They are initially
created during engineering and hold information of diagnostic protocols and diagnostic
data. During further steps along the process chain, like manufacturing, the ODX data are
reused and extended by additional information. The single source principle allows data
reuse for service applications and provides a direct and cost efficient feedback mechanism
for all applications along the process chain.
2

Figure 2: Data exchange in MVCI systems
The open generic approach of MVCI sets no limits concerning applications, protocols
or VCI capabilities. The D-PDU API (application programmer’s interface) provides a
flexible generic API to vehicle communication interfaces with benefits as follows:
D-PDU API allows scalable systems with multiple VCIs, even from different
suppliers
Standardized tool integration with one D-PDU API DLL per VCI supplier
No limitations and restrictions concerning protocol support
Usage directly by applications or in combination with D-server
Standardized communication parameters for standard protocols, defined for
usage with ODX files
API specification allows high performance multilink applications
Flexibility for tool supplier and OEM
3

1.2 D-PDU API products from Softing
Since Softing actively contributes to D-PDU API, MVCI and ODX standardization work in
ASAM and ISO for many years, Softing is able to offer a comprehensive D-PDU API product
portfolio for DTS tools, EDIC, CAN and third-party hardware interfaces. Additional
supplements, complementary products and services for complete MVCI solutions can be
provided as well.
Figure 3 gives an overview about available D-PDU API products and solutions.
Figure 3: D-PDU API products and solutions from Softing
1.2.1 D-PDU API software for vehicle communication interfaces
The D-PDU API software for vehicle interfaces is available for EDIC and CAN interfaces from
Softing. For third-party interfaces the Softing D-PDU API is also available on request.
Supported protocols see chapter 6.3.2.
4

D-PDU API for EDIC vehicle interfaces from Softing
The D-PDU API software is available for the vehicle interfaces EDICcard2, EDICusb,
EDICblue, EDICwlan and EDICpci.
Unlike other vehicle interfaces, the protocol stack is realized as embedded software with all
EDIC interfaces. Reliable real-time behavior is ensured as the stack is executed directly on the
interface hardware – independent of the PC.
D-PDU API for CAN vehicle interfaces from Softing
The D-PDU API software is available for the CAN interfaces CANcard2, CAN-AC2, CAN-
PRO2-PCIE and CANusb. The protocol stack for CAN vehicle interfaces is part of the D-PDU
API PC software. The available protocol performance is dependent on the system resources
like processor performance or memory available for the protocol stack software.
D-PDU API software for third-party vehicle interfaces
Vehicle interfaces from third parties with a proprietary interface can be equipped with
D-PDU API software on request. This means that existing interfaces can be integrated into
new applications with a D-PDU API interface.
1.2.2 Diagnostic Tool Set with D-PDU API support
All DTS V7 products (with the Version 7.65 or higher) support Softing EDIC and CAN vehicle
interfaces as well as some third-party vehicle interfaces with the Softing D-PDU API. The
relevant protocol support depends on the interface being used.
5

6
1.3 Documentation
This document includes a description of system requirements, the scope of delivery and
installation aspects. In addition it describes Softing specific addons, like demo code and the
test application. The documentation gives a short overview about MVCI and the D-PDU API. It
roughly explains the principles and functionality of the D-PDU API and contains information to
the Softing specific implementation.
Therefore the availability or knowledge of the ISO specification is expected as
precondition. The related ISO documentation is listed in chapter 1.3.1.
1.3.1 Related standards
Since MVCI and D-PDU API are standardized by ISO, the corresponding ISO standards are
required in addition to this documentation to use the D-PDU API software. Below the related
standard documents are listed. For a complete reference list, please see chapter 13.1.
/2/ ISO 22900-2 (DIS): specifies the complete D-PDU API, including API functions,
data structures, parameters, sequence charts etc. This document is required for
programming own applications or integrating MVCI system components. The
document can be purchased at www.iso.org. Draft document versions are available
to ISO standardization core team members only.
Note:
The current implementation is based on the ISO 22900-2 specification V2.2.0.
/3/ ISO 22900-3 (DIS): specifies the D-Server API. This document is required for
application programmers or integrators of diagnostic applications, which use 3D-
servers. For pure D-PDU API applications this document is not required.
/4/ ISO 22901-1 (DIS): specifies the ODX data model. This document is required for
users creating and maintaining ODX databases. For D-PDU API applications without
ODX use this document is not required.
1.3.2 Further documents
In addition to this documentation the following files of the software distribution can be used for
further information:
File name Description
<InstDir>DOCDocumentation
_PDU-API_.....pdf
Protocol specific documentations
PDUAPI_Demonstrator
PDU_API.H
Headerfile for D-PDU API applications with data
types, structures and error codes
PDUAPI_Demonstrator
PDUAPI_WRAPPER.H
Headerfile for D-PDU API applications with API
function prototypes
VECOM MDF_SoftingAG_EDIC-
PDU-API_x.yy.zzz.xml
MDF file for D-PDU API applications (x,yy,zzz
replaced by current version number)
VECOM CDF_SoftingAG_EDIC-
PDU-API_x.yy.zzz.xml
CDF file for D-PDU API applications (x,yy,zzz
replaced by current version number)
Table 1: Software distribution documents

2 System requirements
2.1 Hardware
To use the D-PDU API software a PC and at least one of the supported vehicle
communication interfaces is required. The specific hardware requirements are listed below:
A standard PC, capable to run Windows XP (32 Bit) or Windows 7 (32 Bit or 64
Bit)
At least one of the supported vehicle communication interfaces:
o Softing EDICcard2, EDICpci, EDICusb, EDICblue, EDICwlan
o Softing CANcard2, CAN-AC2-PCI, CAN-PRO2-PCIE, CANusb
2.2 Software
To use the D-PDU API software on a PC the following software requirements exist:
PC operating system: Windows XP with SP2 (at least), Windows 7 (32 Bit or 64
Bit)
For programming of own D-PDU API applications the following development tools
are required:
o Microsoft Visual Studio 2005 or later (to use the enclosed D-PDU API
Demonstrator source code)
Or
o Microsoft Visual Studio 6.0 (without using the enclosed D-PDU API
Demonstrator source code)
Notes: The MS Visual Studio project of the enclosed D-PDU API
Demonstrator code requires Visual Studio 2005!
7

8
2.3 Licensing
The D-PDU API software is licensed per vehicle communication interface:
License bound to VCI
serial number
Available for Softing VCIs EDICcard2, EDICpci, EDICusb,
EDICblue, EDICwlan, CANcard2, CAN-AC2-PCI, CAN-PRO2-PCIE
and CANusb
Table 2: Licensing model
Notes:
The license check is executed during the API function call PDUCreateComLogicalLink. In case
of a missing license the function will report an error code PDU_ERR_FUNCTION_FAILED
plus a special value as ComLogicalLink handle. For details please see chapter 7.1.3.18.

3 Scope of delivery
3.1 System components
The D-PDU API software is delivered together with EDIC vehicle communication interfaces
from Softing. For CAN vehicle communication interfaces the D-PDU API is available as well.
The D-PDU API software’s scope of delivery contains the following:
D-PDU API software on CD including:
o Setup program
o Configuration files (root file, MDF, CDF) [installed by setup]
o Demo application in source code [installed by setup]
o Interactive test application [installed by setup]
Installation notes
Protocol Documentation
During the installation process the software is installed and registry entries are made
according to the ISO 22900-2 specification. After installation the Softing specific D-PDU API
DLL “PDUAPI_SoftingAG_x.yy.zzz.dll” (with “x.yy.zzz” for version number) is available on the
system. For details, please see chapter 4.1.
3.2 Configuration files
The installation process installs a root file according to the ISO 22900-2 – 9.7.2.1 specification
or modifies an existing one (if available). In addition an module description file
“MDF_SoftingAG_EDIC-PDU-API_x.yy.zzz.xml” and cable description file
“CDF_SoftingAG_EDIC-PDU-API_x.yy.zzz.xml” are installed, which carry module and cable
information for the Softing D-PDU API software distribution. The files have entries according to
the current support of interface hardware and functionality (for details see chapters 2.1, 7 and
8).
3.3 Applications
To effectively support the user in developing his own applications using the D-PDU API or
using D-PDU API applications two applications are enclosed in the D-PDU API software
distribution:
Small demo application with source code to support the user to develop a custom
application.
Interactive test application with graphical user interface to easily test the behaviour of
the D-PDU API software or to make the first steps without programming.
For details concerning these applications please see chapter 9.
9

4 Installation
To use the D-PDU API software with a vehicle communication interface the D-PDU API
software has to be installed before installation of the VCI hardware. Thereafter the installation
can be tested.
4.1 Software installation
For EDIC vehicle communication interfaces from Softing the operating software is distributed
as part of the D-PDU API software package.
Please make sure to install the software before the hardware is connected to or
integrated in your system.
If no EDIC driver is available on your system the EDIC driver installation will be executed by
default. Please select the EDIC type to be used with the D-PDU API software. In case that
other VCI types than EDIC shall be used, please select any EDIC type as default (e.g.
EDICcard2) and proceed with the setup process.
If Softing CAN hardware interfaces shall be used with D-PDU API software, please install the
CAN drivers with the CAN-L2-API from your CAN installation disk delivered with your
hardware. As an alternative the drivers are also available from the Softing web site
www.softing.com.
If 3rd
party hardware interfaces shall be used with the D-PDU API software, please install the
drivers supplied by the hardware vendor.
During the installation process of the D-PDU API software for VCIs the software is installed
and registry entries are made according to the ISO 22900-2 – 9.7.2.1 specification.
4.2 Hardware installation
After installation of the D-PDU API software and required driver software the VCI hardware
has to be installed or integrated in the system. For details concerning hardware installation
please see the hardware specific user manual supplied with the VCI hardware.
4.3 Test your installation
To test your installation the D-PDU API demo or test application can be used. Please make
sure, that the licensed VCI hardware is connected to your PC. For details concerning the test
application please see chapter 9.
Note: In case of trouble a trace mechanism can be activated. For further details please see
chapter 12.3.
10

11
5 Uninstall
To uninstall the D-PDU API software from your system please select the entry “Softing D-PDU
API for VCIsUninstall”.
Please regard, that additional VCI driver software has to be uninstalled separately.

6 Integration of the D-PDU API
6.1 General information
The D-PDU API is an application programmer’s interface for vehicle communication
interfaces. It provides an open, standardized API according to the ISO 22900-2
specification including standardized communication protocols and –parameters. They are
such defined to be used with ODX files. This offers the advantage of easy data reuse in
many applications. The protocol handling is completely covered by the D-PDU API
software, which reduces the effort for application implementation and maintenance. The D-
PDU API’s ability to run parallel communication on multiple links offers high flexibility and
easy scalability of vehicle communication systems. The event driven application interface
and powerful communication mechanisms are valuable for event driven and parallel
communication with ECUs.
The following chapters will give a short overview about key concepts and features. For
details please refer to the ISO specification [ISO 22900-2].
The D-PDU API functions and IOCTL commands are referenced in chapter 7.
12

6.2 D-PDU API system topologies
The D-PDU API allows setting up scalable systems with different system topologies. Each tool
supplier provides one D-PDU API DLL for his VCIs. The DLL is loaded dynamically by the
client application.
Figure 4: D-PDU API system with single VCI module
13

If multiple VCIs shall be used in the system two possibilities exist. If the VCIs are provided
from the same tool supplier, the tool supplier’s D-PDU API DLL already loaded by the client
application will support multiple VCIs.
Figure 5: D-PDU API system with multiple VCI modules from one tool supplier
If the VCIs are provided from different tool suppliers, multiple D-PDU API DLLs are
dynamically loaded by the client application – one per tool supplier.
Figure 6: D-PDU API system multiple VCI modules from different tool suppliers
14

6.3 D-PDU API functionality
The D-PDU API uses ComLogicalLinks for the communication with ECUs. A ComLogicalLink
is a logical connection for ECU communication via one physical communication bus of a VCI
module. A ComLogicalLink is created via the D-PDU API function call
PDUCreateComLogicalLink (see chapter 7.1.3.18), specifiying a fixed assignment of module,
bus and communication protocol by arguments.
ComParameters (= communication parameters) control the VCI’s protocol processing and
behaviour for the ComLogicalLink. For standardized communication protocols the
ComParameters are defined in the D-PDU API specification [ISO 22900-2 –B.4].
ComPrimitives are used to send and receive data to or from the ECU, as well as for updating
ComParamter values. ComPrimitives combine the send/receive data with control data and
additional information like timestamp values. The behaviour of send/receive ComPrimitives
can be controlled by the ComPrimitive control data. Thus complex communication patterns
with single or cyclic communication can be realized easily and flexibly (e.g. send/receive, send
only, receive only etc.). Depending on the vehicle bus system and communication protocol
being used, one or multiple ComPrimitives may be active at a time per each ComLogicalLink.
This behaviour is controlled internally by the D-PDU API software. These capabilities may be
different in D-PDU API implementations of different vendors (e.g. max. number of active
ComPrimitives for CAN Layer 2 communication).
The D-PDU API provides powerful mechanisms to bind result data to request data. Thus the
complexitiy of vehicle communication is removed from the application, which significantly
reduces the application programming effort.
The D-PDU API effectively supports event driven communication using callback functions. For
simple applications polling can be used as alternative.
15

6.3.1 ComLogicalLinks
A ComLogicalLink selects a resource when it is created. A resource is the physical hardware,
the external pin(s), and the protocol to be used with the resource. If a resource is shareable,
then another ComLogicalLink can be created with the same resource. A ComLogicalLink can
be configured for a single ECU (physical addressing) and for multiple ECUs (functional
addressing.)
Figure 7: D-PDU API system with 3 ComLogicalLinks on 1 resource
16

6.3.2 Communication protocols
The D-PDU API supports several standardized communication protocols.
For each of the standardized communication protocols defined in the D-PDU API specification
a unique protocol name is defined. Since many protocols are typically composed as a
combination of up to 3 communication layers (i.e. reduced/combined ISO OSI layer scope) the
relevant ComParameters are assigned to up to 3 layers. Thus an easy reuse of already
defined parameters is possible for multiple protocols. This is valuable especially for defining
protocol variants (e.g. UDS protocol on different physical or transport layers). The table below
gives a short overview. For more details about these protocols see the ISO D-PDU API
specification [ISO 22900-2 – B.1.3]. For customer specific protocols see documentation in
folder (<InstDir>DOC).
Table 3: Standardized communication protocols
17

6.3.3 ComParameters
The D-PDU API ComParameters allow full abstraction of all protocol knowledge into the VCI
module. The combination of the unique protocol name defined for the standardized protocols
and the associated ComParameters uniquely define a ComLogicalLink to one or multiple
ECUs.
The ComParameters are assigned to 3 layers for easy reuse and combination of already
existing parameters (e.g. UDS on different physical or transport layer):
Physical layer
Transport / Data link layer
Application layer
An additional parameter class value (e.g. timing parameter, bus parameter, etc.) allows easy
structuring, data modeling and tool access.
The table below gives an example of the documentation used in the D-PDU API specification
(E=ECU, T=Tester, S=Standard, O=Optional). For more details, please refer to the ISO
specification [ISO 22900-2 – B.10].
Table 4: Communication parameter table (example)
18

In addition to the parameter tables the ISO specification gives detailed explanations of each
ComParameter including parameter name type, range, resolution and default values. An
example is shown in the table below:
Table 5: Communication parameters (example)
6.3.4 ComPrimitives
ComPrimitives provide powerful and flexible mechanisms to send and receive data. They
support binding of request and response data and carry additional information (e.g.
timestamp). Complex communication patterns (e.g. periodic, send/receive only, response on
event, etc.) are effectively supported by control data. The following D-PDU API ComPrimitive
types are defined
• PDU_COPT_STARTCOMM
• PDU_COPT_STOPCOMM
• PDU_COPT_SENDRECV
• PDU_COPT_DELAY
• PDU_COPT_UPDATEPARAM
• PDU_COPT_RESTORE_PARAM
For further details please refer to the ISO specification [ISO 22900-2 – D.1.2].
19

6.4 D-PDU API tool integration
The integration of D-PDU API VCIs in applications is realized via standardized description
files.
• A root file is used for system wide integration of D-PDU API DLLs from different
suppliers. It is the main entry point for applications. During installation each
vendor’s setup routine adds the information about the vendor’s D-PDU API
software to the root file.
• A MDF.xml file (=module description file) is used for each VCI. It describes the
VCI‘s capabilities. Each vendor delivers the MDF file together with his VCI
module.
• A CDF.xml file (= cable description file) is used for the description of the cable
connection between VCI and vehicle. It is delivered by the tool supplier or cable
supplier.
For more information about the description files and the integration of the D-PDU API in an
application see the D-PDU API specification [ISO 22900-2 – 9.3].
20

21
6.5 D-PDU API migration support
The D-PDU API is designed to allow migration and reuse of existing hardware and
software components in D-PDU API systems. In this context J2534 and RP1210a
functionality is supported by the D-PDU API. The mapping of J2534/RP1210a functions
and error codes to D-PDU API functions, ComParameters and error codes is described in
the D-PDU API specification [ISO 22900-2 - 10]. The adaption and integration work is
realized by additional software layers, which have to be optionally implemented if required.
The figure below shows an example system structure with migrated components:
Figure 8: D-PDU API migration system example

7 API reference
Below the D-PDU API functions, IOCTL commands, data types and structure will be listed. In
addition specific information and limitations of the current implementation will be described.
Note: In case of trouble during application programming a trace mechanism can be activated.
For further details please see chapter 12.3.
7.1 API functions
7.1.1 Overview
The table below lists all D-PDU API functions and gives a short description. For details please
refer to chapter 7.1.3.
Function Function overview
General
PDUConstruct The function is a constructor with optional, manufacturer-specific arguments. It
must be called before any other D-PDU API function call for each D-PDU API
implementation.
PDUDestruct This destructor must be the last function called in order to free all resources.
PDUModuleConnect The function is used to connect to a specific MVCI protocol module.
PDUModuleDisconnect The function is used to disconnect from a specific MVCI protocol module.
PDURegisterEventCallback A callback function is registered or unregistered for event notification.
PDUIoCtl I/O control functions of a MVCI Protocol Module or ComLogicalLink are inkoked.
Information
PDUGetVersion Version information for a specified MVCI Protocol Module and its D-PDU API
implementation is returned by this function.
PDUGetStatus Runtime information from a MVCI Protocol Module, ComLogicalLink or
ComPrimitive is returned.
PDUGetLastError Returns the code for the last generated error from a MVCI Protocol Module or
ComLogicalLink.
PDUGetObjectId For a given shortname and PDUObjectType the Id is returned. Also the MDF file
can be parsed.
Resource Management
PDUGetResourceIds According to the requested resource information, all matching resource Ids are
returned.
PDUGetResourceStatus The status of the requested resource Id is returned.
PDUGetConflictingResources The function returns a list of resource Ids that are in conflict with the given
resource Id.
PDUGetModuleIds If there are any MVCI Protocol Modules currently connected to the D-PDU API,
their Ids are returned.
PDULockResource The requested resource Id is locked
PDUUnLockResource The locked requested resource Id is released.
22

Function Function overview
ComLogicalLink
Handling
PDUCreateComLogicalLink A ComLogicalLink is created for a given D-PDUResource.
PDUDestroyComLogicalLink The ComLogicalLink is destroyed.
PDUConnect The created ComLogicalLink is physically connected to the communication line.
PDUDisconnect The connected ComLogicalLink is physically disconnected from the
communication line.
PDUGetTimestamp The function obtaines the current time (hardware clock) from a MVCI Protocol
Module.
Link and ComParameter
Handling
PDUGetComParam The current value of specified ComParameter is returned
PDUSetComParam The specified ComParameter is set to given value. Any previous values are
overwritten.
PDUGetUniqueRespIdTable A table of Unique Response Identifiersis returned. Each URID is associated with
a set of ComParameters that uniquely define an ECU response.
PDUSetUniqueRespIdTable The table of Unique Response Identifiers is set. Each value is assigned by the
Application.
Message Handling
PDUStartComPrimitive The ComPrimitive operation starts.
PDUCancelComPrimitive The current execution of the given ComPrimitive is cancelled.
PDUGetEventItem Retrieves the item data for a given event source
PDUDestroyItem The given item is destroyed.
Table 6: D-PDU API functions
7.1.2 General usage
In order to initialize the D-PDU API implementation and to prepare communication for one
channel, the application has to go through a sequence of D-PDU API function calls. The demo
applicatioin provides an example for the D-PDU API usage. For more information see chapter
9.1.
7.1.2.1 General usage of D-PDU API function calls
7.1.2.1.1 Initialization of the D-PDU API Library
The D-PDU API library is initialized by calling the PDUConstruct function. PDUGetModuleIds
will return a list of the MVCI Protocol Modules available, their handles and module types.
PDURegisterEventCallback may also be called and the global system callback will be
registered.
7.1.2.1.2 Connecting to a MVCI Protocol Module
When calling PDUModuleConnect the D-PDU API library will connect to one or more MVCI
Protocol Modules.
PDURegisterEventCallback may also be called and the module callback will be registered.
23

7.1.2.1.3 Setting up a ComLogicalLink
Based on the resource information PDUCreateComLogicalLink will create a ComLogicalLink.
PDURegisterEventCallback may also be called to register the ComLogicalLink’s callback
function.
PDUGetUniqueRespIdTable obtains a set of ComParameters for unique identification of
ECUs.
PDUGetComParam returns the ComParameter item structures. PDUSetComParam sets the
ComParameters for the ComLogicalLink.
When PDUSetUniqueRespIdTable is called the URID Table is configured based on the ECU
responses expected to be received on the ComLogicalLink.
When calling PDUConnect the ComLogicalLink will connect to the communication line.
7.1.2.1.4 Initiating vehicle communications on a ComLogicalLink
PDUStartComPrimitive is used to start the vehicle communications on the ComLogicalLink. As
parameters it may have PDU_COPT_STARTCOMM or PDU_COPT_SENDRECV.
PDU_COPT_STARTCOMM ComPrimitive is used for initialization of ECU communication and
to start sending tester present messages. Some protocols require that this is the first
ComPrimitive being called. The PDU_COPT_SENDRECV ComPrimitive is used to begin
vehicle communications for all other vehicle bus communications.
7.1.2.1.5 Communicating on a ComLogicalLink with the vehicle
PDUStartComPrimitive (with type PDU_COPT_SENDRECV) will set up and start
ComPrimitives for vehicle bus communication (Send only, Send Receive, or Receive only).
In order to change ComParameters during communication the PDUSetComParam function is
used.
PDUGetEventItem will retrieve event items and PDUDestroyItem will destroy event items from
D-PDU API memory, when they are not needed any longer by the application.
7.1.2.1.6 Stopping the vehicle communication on a ComLogicalLink
PDUStartComPrimitive (with type PDU_COPT_STOPCOMM) will stop diagnostic
communication on a ComLogicalLink.
7.1.2.1.7 Connecting to an additional MVCI Protocol Module
When a system event callback is received with an information type PDU_IT_INFO indicating
that a new MVCI Protocol Module is detected by D-PDU API, the list of modules will change
(PDU_INFO_MODULE_LIST_CHG).
The function PDUGetModuleIds returns the new list of available MVCI Protocol Modules and
their handles and modules types. Any previously detected MVCI Protocol Modules will return
the same hMod handles.
When calling PDUModuleConnect is called, a connection to the new MVCI Protocol Modules
is established.
PDURegisterEventCallback may also be called to register the new module’s callback function.
24

7.1.2.1.8 Reconnecting to a MVCI module after loss of communication
When a module event callback is received, it indicates that communication to an MVCI
protocol module is lost. The hMod information is part of the callback information.
When PDUModuleDisconnect is called, the hMod handle is no longer valid. Also all event
items in the queues are freed, and any related module memory reserved by the D-PDU API
library is released.
Wait for a system event callback with an information type PDU_IT_INFO indicating the list of
modules has changed (PDU_INFO_MODULE_LIST_CHG).
The function PDUGetModuleIds returns the new list of available MVCI Protocol Modules and
their handles and modules types. If communication is lost, the hMod will no longer be listed as
available.
7.1.2.1.9 Disconnecting from a MVCI module
When PDUDisconnect is called, the ComLogicalLink is disconnected from the communication
line.
PDUDestroyComLogicalLink destroys the ComLogicalLink.
PDURegisterEventCallback may also be called with a NULL parameter to unregister the
module callback function. Thereafter no further events will be signalled to the application for
that module.
PDUModuleDisconnect will disconnect a specific MVCI Protocol Module from the D-PDU API
library and release all reserved memory resources.
7.1.2.1.10 Deinitialization of the D-PDU API library
The PDUDestruct function call will deinitialize the D-PDU API. All internal resources are
destroyed or released.
7.1.2.2 Asynchronous communication
The D-PDU API is designed for asynchronous operation, i.e. API calls are immediately
returned even though the requested activity might still be running or is still waiting for
execution inside the D-PDU API implementation. The D-PDU API is designed for
asynchronous calls, because all vehicle communication requirements (e.g. non cyclic, cyclic,
event driven communication, etc.) and synchronous communication requirements resulting
from SAE J2534 and RP1210a can be covered by this principle.
The D-PDU API functions allow the application to use both asynchronous and synchronous
communication principles to exchange data with the D-PDU API:
Asynchronous Mode: In this case, the communication between application/server and the PDU
API implementation is completely event driven. The application may register an
application/server specific callback function by calling PDURegisterEventCallback. Any
events occurring will cause the callback function to be invoked.
Synchronous Mode (Polling Mode): In this case, the application does not make usage of the
callback mechanism. It initiates the PDU API functions just as in asynchronous mode.
Instead of waiting for notification, it repeats requesting the status by calling the
PDUGetStatus API function.
25

7.1.2.3 Synchronous communication
The PDU API does not support synchronous function calls, i.e. PDU API function calls do not
wait until the requested service is finished before returning the call.
In order to cover synchronous function calls, as e.g. for SAE J2534 or RP1210a, the
application or server has to operate the PDU API in polling mode or needs to provide a simple
callback function. For SAE J2534 and RP1210a, synchronous calls as defined by these
standards will be transparently mapped onto the asynchronous PDU API calls. This is done by
optional compatibility layers.
26

7.1.2.4 Usage of ComPrimitives
A ComPrimitive is a basic communication element holding data and controlling the exchange
of data between the PDU API implementation and the ECU. There are different types of
ComPrimitives in order to describe different communication principles and to give an overview
of the generic data exchange mechanism. Depending on the communication protocol used
with a specific ComLogicalLink, each ComPrimitive has a different behavior and usage.
The following table describes the different ComPrimitive types.
ComPrimitive type/value Description
PDU_COPT_STARTCOMM
0x8001
The communication with the ECU is started; an optional
request will be sent to the ECU. The detailed behaviour
of this ComPrimitive is protocol dependent. This
ComPrimitive is required as the first ComPrimitive for
certain diagnostic protocols. The ComLogicalLink is put
into PDU_CLLST_COMM_STARTED state, which
allows for tester present messages to be enabled
according to the ComParameter settings.
PDU_COPT_STOPCOMM
0x8002
The communication with ECU is stopped; an optional
stop request will be sent to the ECU. The detailed
behaviour is protocol dependent. The ComLogicalLink
is put into PDU_CLLST_ONLIINE state and no further
tester present messages will be sent. To begin
communications again PDU_COPT_STARTCOMM
ComPrimitive might be required by some protocols.
PDU_COPT_UPDATEPARAM
0x8003
The ComParameters and the UniqueRespIdTable
related to a ComLogicalLink are copied from the
working buffer to the active buffer. Before the update
PDUSetComParam and/or PDUSetUniqueRespIdTable
are called to pass the values to the D-PDU API, which
modifies the working buffer.
PDU_COPT_SENDRECV
0x8004
Send request data and/or receive corresponding
response data (single or multiple responses).
PDU_COPT_DELAY
0x8005
Wait the given time span before executing the next
ComPrimitive.
PDU_COPT_RESTORE_PARAM
0x8006
Converse functionality of
PDU_COPT_UPDATEPARAM. Copies
ComParameters related to a ComLogicalLink from
active buffer to working buffer.
Table 7: ComPrimitives
The following sections describe how to use ComPrimitives for different communication
patterns known from automotive communication protocols. All actions described assume the
D-PDU API has been initialized and a ComLogicalLink has been created. In addition to the
D-PDU API function calls shown in the tables, additional API calls can be used for additional
functions like status requests etc. Any memory allocation or deallocation is initiated by create,
start and destroy calls and is handled within the D-PDU API.
27

7.1.3 Details
The subchapters below give a short description of the D-PDU API functions, parameters and
error codes. For further details please see the ISO 22900-2 specification.
28

7.1.3.1 PDUConstruct
Syntax
EXTERNC T_PDU_ERROR PDUConstruct(CHAR8* OptionStr, void *pAPITag)
Parameters
OptionStr PDUConstruct does NOT require a Softing specific OptionsStr. Therefore
NULL is used as parameter
pAPITag An Application defined tag value. Used in event callbacks. The callbacks
indicate status, errors and results for the PDU API library being used. This
information can be used to determine which library is raising the callback.
Function Description
The D-PDU API library is initialized. The list of all available MVCI Protocol Modules and their
supported resources is determined by the D-PDU API library. The library also creates internal
structures, including a resource table. The state of the communication is offline. This means
that no allocation of resources and no communication over vehicle interfaces take place.
The OptionStr is validated and all known and accessible MVCI Protocol Modules are detected.
Module IDs are assigned to all properly initialized MVCI Protocol Modules
A PDU_MODULE_DATA list is created. The list contains MVCI Protocol Modules, their module
types, module handles, module status and additional vendor information strings.
An internal resource table stores all detected resources. For any resource query this table will
be used. The query can be done via the functions PDUGetModuleIds,
PDUGetConflictingResources, PDUGetResourceIds, PDUGetResourceStatus,
PDULockResource, and PDUUnlockResource.
Return values
Return value definition Description
PDU_STATUS_NOERROR Function call successful
PDU_ERR_FCT_FAILED Function call failed
PDU_ERR_DEVICE_NOT_CONNECTED The D-PDU API implementation does not
support any of the connected MVCI Protocol
Modules
PDU_ERR_SHARING_VIOLATION Function called again without a previous
destruct
PDU_ERR_INVALID_PARAMETERS There is at least one option attribute that has
invalid parameters
PDU_ERR_VALUE_NOT_SUPPORTED The D-PDU driver does not support at least one
of the option values
Table 8: PDUConstruct return values
29

7.1.3.2 PDUDestruct
Syntax
EXTERNC T_PDU_ERROR PDUDestruct()
Parameters
None
All open communication links are closed and all communication resources are released.
Internal memory segments are deallocated and system-level drivers disconnected. The
execution of PDUDestruct does not result in any communication on the vehicle interfaces.
PDUConstruct may be called again after execution of PDUDestruct.
The internal resource table is checked. Any open communication links are determined and
closed. No communication takes place.
All MVCI Protocol Modules detected before with PDUConstruct are de-initialised.
All connections to connected MVCI Protocol Modules are closed.
All internal memory resources are released.
Return values
PDU_ERR_DEVICE_NOT_CONNECTED The D-PDU API implementation does not
support any of the MVCI Protocol Modules
connected
Table 9: PDUDestruct return values
30

7.1.3.3 PDUModuleConnect
Syntax
EXTERNC T_PDU_ERROR PDUModuleConnect (UNUM32 hMod)
Parameters
hMod Handle of the MVCI protocol module to be connected. The D-PDU API will
establish connection to all detected MVCI protocol modules if the handle is set
to PDU_HANDLE_UNDEF. The MVCI protocol module vendor will choose the
interface type of the connection.
A connection to the specified MVCI protocol module is established and its system-level drivers
are initialized. Available resources can be obtained from the specified MVCI protocol module.
Internal structures are created, including a resource table. The state of the communication is
offline. This means that no allocation of resources and no communication via vehicle
interfaces take place.
It is determined if a connection to a MVCI protocol module is available. In this case the module
must have the state PDU_MODST_AVAIL.
The communication with the specific MVCI protocol module is initialized.
All resources status values of the MVCI protocol module are determined.
The Module Status is set to PDU_MODST_READY. (Note: a callback can not be registered by
the client before connection. Therefore no event callback is generated at that moment).
If the Module Status is not in PDU_MODST_READY state, all D-PDU API function calls
requiring a “hMod” parameter will return with error PDU_ERR_MODULE_NOT_CONNECTED.
The following D-PDU API functions are allowed to be used prior to a PDUModuleConnect:
PDUGetResourceIds
PDUGetObjectId
PDUGetConflictingResources
PDUGetStatus
The handle (hMod) remains valid from the beginning of the connection of the module until a
PDUModuleDisconnect function call, even if there is a loss of communication with the module.
In this way it is possible to maintain the event queues for the client application’s retrieval of
event items.
Use Case specific behaviour
For the corresponding use cases a status event item is generated each time a MVCI Protocol
Module changes it’s status:
Use Case:
Module State = PDU_MODST_AVAIL:
- Initial detection by the D-PDU API.
- NO status event item is generated
- For any API function call to the module the state must be PDU_MODST_READY
31

Use Case: Module State = PDU_MODST_UNAVAIL:
- Initial detection by the D-PDU API, but already in use by another client session
- A module may transition to PDU_MODST_UNAVAIL if the D-PDU API detects a loss
of communication to the module after being in the READY state.
Use Case: Module State Change = (PDU_MODST_AVAIL -> PDU_MODST_READY):
- The transition is made after a successful call to PDUModuleConnect.
- API session between the module and the client application can be initiated
- NO status event item can be generated (the function callback
PDURegisterEventCallback can be called in the state PDU_MODST_READY only).
Use Case: Module State Change = (PDU_MODST_READY -> PDU_MODST_UNAVAIL):
- The transition is made after a loss of communication to a module.
- All ComPrimitives currently executing (i.e. periodic) and all ComPrimitives in the CoP
queue will be cancelled (PDU_COPST_CANCELLED).
- All active ComLogicalLinks will go into the offline state (PDU_CLLST_OFFLINE).
- In the case of losing communications to a module the event order is:
PDU_COPST_CANCELLED, PDU_CLLST_OFFLINE, and PDU_MODST_UNAVAIL.
Use Case: Module State Change = (PDU_MODST_READY -> PDU_MODST_NOT_READY):
- The transition is made when a condition occurs on the device which does not allow the
execution of any further API calls. This may not be a permanent condition (e.g the
module recovers from the not ready state (e.g. PDU_IOCTL_RESET)).
Use Case: Module State Change = (PDU_MODST_READY -> PDU_MODST_AVAIL):
- The transition is made after a successful call to PDUModuleDisconnect.
- All resources are released for the module.
- NO status event item is generated since further event items will not be queued for the
module.
Return values
PDU_ERR_PDUAPI_NOT_CONSTRUCTED D-PDU API has not been constructed before
PDU_ERR_INVALID_HANDLE Invalid MVCI protocol module handle
PDU_ERR_MODULE_FW_OUT_OF_DATE The version of the D-PDU API library is
newer than the MVCI Protocol Module
firmware. The MVCI Protocol Module
firmware must be updated
PDU_ERR_API_SW_OUT_OF_DATE The MVCI Protocol Module firmware version
is newer than the D-PDU API Library. The
D-PDU API Library must be updated
PDU_ERR_FCT_FAILED Command failed
32

Table 10: PDUModuleConnect return values
7.1.3.4 PDUModuleDisconnect
Syntax
EXTERNC T_PDU_ERROR PDUModuleDisconnect(UNUM32 hMod)
Parameters
hMod Handle of the MVCI Protocol Module to be disconnected. If set to
PDU_HANDLE_UNDEF then the D-PDU API will disconnect from all
previously connected MVCI protocol modules.
Any open communication links to the specified VCI module(s) are closed.The specified MVCI
protocol module(s) is deinitialized.
All internal memory associated with the MVCI protocol module(s) is released and system-level
drivers are disconnected.
The Module Status is set to PDU_MODST_AVAIL if communication has not been lost to the
module (further event items are not allowed for the module, so no event callback is
generated). The module handle (hMod) is still valid for further PDUModuleConnect calls.
No communication on the vehicle interfaces is initiated due to the execution of
PDUModuleDisconnect, but PDUModuleConnect may be called again.
In the case that communication to the module has been lost the hMod handle is no longer
valid. After all items have been retrieved from the module event queue the client application
should call PDUModuleDisconnect.
Return values
PDU_ERR_INVALID_HANDLE MVCI protocol module handle is not valid
PDU_ERR_MODULE_NOT_CONNECTED MVCI Protocol Module is not connected
Table 11: PDUModuleDisconnect return values
33

7.1.3.5 PDURegisterEventCallback
Syntax
EXTERNC T_PDU_ERROR PDURegisterEventCallback(UNUM32 hMod, UNUM32
hCLL, CALLBACKFNC EventCallbackFunction )
Parameters
hMod Module handle if a module/system event callback function shall be registered.
If hCLL=PDU_HANDLE_UNDEF the callback function shall be used for
PDUAPI system events.
hCLL ComLogicalLink handle, if a ComLogicalLink event callback function shall be
registered. If no ComLogicalLink specific callback function shall be registered,
the value PDU_HANDLE_UNDEF shall be passed. A callback registration to a
ComLogicalLink can not be requested if a ComLogicalLink is already
connected. If such a request is made an error is returned.
EventCallbackFunction
It can be used for event notification as a reference of callback function. If
NULL the callback mechanism is deactivated.
The function is used to register or unregister a callback function for event notification which is
by default deactivated.
The input parameter’s handles are validated. If all handles are PDU_HANDLE_UNDEF it is an
event registration for D-PDU API system events.
The request type is determined. It may be a register or a un-register request.
The callback function pointer is added or removed to the proper object (System, Module,
ComLogicalLink).
Return values
PDU_ERR_PDUAPI_NOT_CONSTRUCTED PDU API has not been constructed before
PDU_ERR_INVALID_HANDLE MVCI Protocol Module handle or
ComLogicalLink handle is invalid
PDU_ERR_COMM_PC_TO_VCI_FAILED Communication between host and MVCI
Protocol Module was not successful
PDU_ERR_MODULE_NOT_CONNECTED MVCI Protocol Module has not been
connected
PDU_ERR_CLL_CONNECTED ComLogicalLink is in the ONLINE state;
registration of a new callback can not be
accepted
Table 12: PDURegisterEventCallback return values
34

7.1.3.6 EventCallback
Syntax
void EventCallback (T_PDU_EVT_DATA eventType, UNUM32 hMod, UNUM32
hCLL, void *pCllTag, void *pAPITag)
Parameters
eventType Type of event which occurred.
hMod Handle of MVCI Protocol Module (in case of a system event callback it has the
value PDU_HANDLE_UNDEF).
hCLL Handle of ComLogicalLink causing the event (if not from a ComLogicalLink it
has the value PDU_HANDLE_UNDEF).
pCllTag Tag value for a ComLogicalLink. If hCLL = PDU_HANDLE_UNDEF, then the
tag is ignored. It provides information about the source of the event and is
application specific.
pAPITag Tag value for the PDU API. It provides information about the source of the
event and is application specific.
Function description
The prototype must be implemented and registered by the application. When
PDURegisterEventCallback is called the D-PDU API registers the application’s callback
function, so that the callback function will be called for each event furtheron. The callback
function receives the event type, a handle of the resource causing the event and an
application-specific tag. The event may be processed by the application immediately or it may
be passed to an internal thread.
To avoid unnecessary blocking of the D-PDU API software, short runtime duration of the
function is highly recommended. The D-PDU API thread is used when the function is called.
The application’s callback function will post an event to wake another thread to process the
event data. During the callback routine only PDUGetEventItem calls are allowed.
Return values
None
35

7.1.3.7 PDUIoCtl
Syntax
EXTERNC T_PDU_ERROR PDUIoCtl(UNUM32 hMod, UNUM32 hCLL, UNUM32
IoCtlCommandId, PDU_DATA_ITEM *pInputData, PDU_DATA_ITEM
**pOutputData)
Parameters
hMod Handle of the specific MVCI Protocol Module, which shall be controlled by the
I/O control command specified. In order to specify module related commands,
the parameter hCLL must be set to PDU_HANDLE_UNDEF
hCLL Handle of the ComLogicalLink, which shall be controlled by the specified I/O
control command.
IoCtlCommandId
ID of the I/O control command. The supported ID’s by a specific MVCI
Protocol Module can be found in the MVCI MDF.
pInputData Input data item for the specified command. If no input data is required, NULL
is used as parameter value. The application creates and manages the input
data item.
pOutputData Call-by-reference place for storing the output data item pointer.
If NULL is used, then the D-PDU API implementation will not allocate or fill the
output data item. If a valid address is provided, the D-PDU API
implementation will allocate a PDU_DATA_ITEM and fill in the output data of
the specified command. A reference is stored in *pOutputData. After usage,
PDUDestroyItem is called and the allocated data item is freed.
Used to execute functions or set values for a MVCI Protocol Module. Each specified IOCTL
function is identified by an ID number and has its own input and output values.
The MVCI MDF (Module Description File) contains the I/O controls supported by a specific
MVCI Protocol Module. When the function is called all input parameters are validated.
The application allocates an input data structure to be taken by the function. From this
structure the required information is extracted and the command is executed. The output data
is allocated and filled in the call-by-reference variable pOutputData. When calling
PDUDestroyItem from the application the OutputData structure is released.
36

Return values
PDU_ERR_INVALID_HANDLE MVCI Protocol Module or ComLogicalLink
handle is invalid
PDU_ERR_ID_NOT_SUPPORTED The MVCI Protocol Module does not support
the ID of I/O control
PDU_ERR_INVALID_PARAMETERS pInputData or pOutputData reference
pointer for an IOCTL Command are invalid
(NULL). The specified IOCTL expects at
least one valid reference pointer
connected
Table 13: PDUIoCtl return values
37

7.1.3.8 PDUGetVersion
Syntax
EXTERNC T_PDU_ERROR PDUGetVersion( UNUM32 hMod, PDU_VERSION_DATA
*pVersionData )
Parameters
hMod Handle of the MVCI Protocol Module for which the version information is
returned.
pVersionData Call-by-reference place for storing the version information
The version information from a MVCI Protocol Module is returned.
When called the function validates all input parameters. Pointer parameters cannot be NULL.
The PDU_VERSION_DATA structure (allocated by the client application) is filled.
Return values
PDU_ERR_INVALID_PARAMETERS pVersionData parameter is invalid ( NULL )
connected
PDU_ERR_INVALID_HANDLE MVCI Protocol Module handle is invalid
Table 14: PDUGetVersion return values
38

7.1.3.9 PDUGetStatus
Syntax
EXTERNC T_PDU_ERROR PDUGetStatus( UNUM32 hMod, UNUM32 hCLL, UNUM32
hCoP, T_PDU_STATUS *pStatusCode, UNUM32
*pTimestamp, UNUM32 *pExtraInfo)
Parameters
hMod Handle of MVCI Protocol Module for which the status code is to be requested.
In order for the status of only one module to be returned, hCLL and hCoP
must be set to PDU_HANDLE_UNDEF.
hCLL Handle of ComLogicalLink for which the status code is to be requested. In
order for the status of only one ComLogicalLink to be returned hCop must be
set to PDU_HANDLE_UNDEF.
hCoP Handle of ComPrimitive for which the status code is to be requested.
pStatusCode Call-by-reference place for storing the status code.
pTimestamp Call-by-reference place for storing timestamp in microseconds.
pExtraInfo Call-by-reference place for storing additional information.
pExtraInfo returns 0 for ComPrimitives.
For MVCI Protocol Modules and ComLogicalLinks, pExtraInfo contains
additional information defined by the MVCI Protocol Module supplier.
If no information is available, the function returns 0.
The function returns runtime information from a MVCI Protocol Module, ComLogicalLink or
ComPrimitive.
When called the function validates all input parameters.
The latest status information for the specified handle (Module or ComLogicalLink or CoP) is
returned. The information is stored in the memory allocated by the client application.
The status PDU_MODST_NOT_READY is returned in the case that the D-PDU API detects a
PC software version out-of-date with the MVCI Protocol Module Firmware.
39

Return values
PDU_ERR_INVALID_PARAMETERS pStatusCode, pTimestamp or pExtraInfo is
invalid (NULL)
PDU_ERR_INVALID_HANDLE MVCI Protocol Module, ComPrimitive or
Table 15: PDUGetStatus return values
40

7.1.3.10 PDUGetLastError
Syntax
EXTERNC T_PDU_ERROR PDUGetLastError( UNUM32 hMod, UNUM32 hCLL,
T_PDU_ERR_EVT *pErrorCode, UNUM32 *phCoP, UNUM32
*pTimestamp, UNUM32 *pExtraErrorInfo)
Parameters
hMod Handle of MVCI Protocol Module for which the error code is requested. To
return the last error of the MVCI Protocol Module, hCLL must be set to
PDU_HANDLE_UNDEF.
hCLL Handle of ComLogicalLink for which the error code is requested.
phCoP phCoP will contain the handle of the ComPrimitive if the last error belonged to
that ComPrimitive, else phCoP is set to PDU_HANDLE_UNDEF.
pErrorCode Call-by-reference place for storing the error code.
pErrorCode will contain PDU_ERR_EVT_NOERROR if no last error has been
stored for the specified handle.
pTimestamp Call-by-reference place for storing timestamp.
pExtraErrorInfo
Call-by-reference place for storing extra error information. The ExtraErrorInfo
code can be found in the MDF file.
The function returns the code for the last error from a MVCI Protocol Module or
ComLogicalLink, which occurred for the handle. To perform error handling the client
application should read the error events from the event queues to get the chronological order
of events.
Notes:
This function has been added for J2534 support via an additional software wrapper. It is not
needed, if the application evaluates the error event items from the queues associated with
callback functions.
In case the LAST error is already removed from the event queue by the time this function is
called, the hCoP handle is no longer valid because the hCoP already finished and its
associated resources are freed.
When the function is called all input parameters are validated. The pointer parameters cannot
be NULL.
The last error information for the specified handle (Module or ComLogicalLink) is stored in the
memory allocated by the client application.
If there is a ComPrimitive error than the ComPrimitive handle is returned with the error code.
41

Return values
PDU_ERR_INVALID_PARAMETERS pErrorCode, pTimestamp or pExtraErrorInfo
is invalid (NULL)
Protocol Module was not sucessfull
connected
handle is invalid
Table 16: PDUGetLastError return values
42

7.1.3.11 PDUGetObjectId
Syntax
EXTERNC T_PDU_ERROR PDUGetObjectId(T_PDU_OBJT pduObjectType, CHAR8*
pShortname, UNUM32 *pPduObjectId)
Parameters
pduObjectType Enumeration ID of object type.
pShortname Pointer to the shortname of object.
pPduObjectId Call-by-reference place where the PDU Object ID for "Shortname" of
pduObjectType is stored. The ID value will be PDU_ID_UNDEF if there is no
valid Object Id for the requested object type and shortname.
Depending on the given item or type given as inputs, the item ID is determined. We can also
obtain the item ID by parsing the MDF file.
When the function is called all input parameters are validated. Pointer parameters cannot be
NULL.The ID of the requested object is returned.
The response parameter pPduObjectId is filled with the information.
Return values
PDU_ERR_MODULE_FW_OUT_OF_DATE The D-PDU API library version is newer than
the MVCI Protocol Module firmware. We
must update the MVCI Protocol Module
firmware.
is newer than the D-PDU API Library. We
must update the D-PDU API Library.
PDU_ERR_INVALID_PARAMETERS There is at least one invalid parameter
(ObjectType, ShortName), or the pointer to
the pPduObjectId is NULL.
Table 17: PDUGetObjectId return values
43

7.1.3.12 PDUGetResourceIds
Syntax
EXTERNC T_PDU_ERROR PDUGetResourceIds(UNUM32 hMod, PDU_RSC_DATA
*pResourceIdData, PDU_RSC_ID_ITEM
**pResourceIdList)
Parameters
hMod Handle of MVCI Protocol Module. If the value of the handle is
PDU_HANDLE_UNDEF then the connected modules return their resource Ids
and the module handles which support the PDU_RSC_DATA elements
pResourceIdData
Call-by-reference place for the resource Id data information for a particular
module type.
pResourceIdList
Call-by-reference place where the Resource Id list for the selected resource
data is stored. When PDUDestroyItem is called the item is destroyed.
The function returns a list of resource ids from the D-PDU API for a given module. The module
must support the resource data information (protocol, bus type and pin(s)). PDUGetObjectId
returns the object Ids for the resource data information.
A reference to a memory object of PDU_RSC_DATA type is given by the caller. The object
refers to a single set resource data information (pResourceIdData). A PDU_IT_RSC_ID object
(pResourceIdList) is generated by the D-PDU API. The object has a list of resource Id’s that
match the given resource data information. After using the resource Id list information, the
function PDUDestroyItem may be called by the application in order to release the D-PDU API
memory.
The function validates the input parameters; pointer parameters cannot be NULL.
Thereafter the function takes the pResourceIdData structure as allocated by the application.
Memory for the pResourceIdList result information is allocated and the required information
from pResourceIdData structure is extracted and the correct list of resource Ids is determined,
that match the resource data requested.
44

Return values
the MVCI Protocol Module firmware. We must
update the MVCI Protocol Module firmware.
PDU_ERR_INVALID_PARAMETERS The pResourceIdData or pResrouceIdList
reference pointer is invalid (NULL)
Table 18: PDUGetResourceId return values
45

7.1.3.13 PDUGetResourceStatus
Syntax
EXTERNC T_PDU_ERROR PDUGetResourceStatus(PDU_RSC_STATUS_ITEM
*pResourceStatus)
Parameters
pResourceStatus
Call-by-reference place where the status of all requested resource Ids is
stored. Before calling the function the data structure is pre-filled with the
resource Ids of interest.
The function returns resource status information from the D-PDU API. The pResourceStatus
structure contains all the resources for which the status shall be retrieved. The same structure
is used when determining the resource status for each requested resource Id.
A reference to a memory object that is an input/output resource status item (pResourceStatus)
is given by the caller. The caller-supplied memory object is of type
PDU_RSC_STATUS_ITEM. Also a pointer to the data item object is provided, specifying the
correct type PDU_IT_RSC_STATUS, and the number of PDU_RSC_STATUS_DATA objects
for which the status shall be retrieved. The D-PDU API validates the object and then fills in the
output portions of the structure.
When the function is called all input parameters are validated; pointer parameters cannot be
NULL. pResourceStatus structure is allocated by the application. For each requested resource
Id the status information is filled.
Return values
PDU_ERR_INVALID_HANDLE MVCI Protocol Module handle contained in
the pResourceStatus strucutre is invalid
PDU_ERR_INVALID_PARAMETERS pResourceStatus, or one or more invalid
resource ids is invalid (NULL)
Table 19: PDUGetResourceStatus return values
46

7.1.3.14 PDUGetConflictingResources
Syntax
EXTERNC T_PDU_ERROR PDUGetConflictingResources(UNUM32 resourceId,
PDU_MODULE_ITEM *pInputModuleList, PDU_RSC_CONFLICT_ITEM
**pOutputConflictList)
Parameters
resourceId The resource identifier used for conflict checking. It can be obtained from the
MDF file and from PDUGetResourceId function.
pInputModuleList
List of modules to determine conflicts against. In this structure hMod and
ModuleType need to be valid.
pOutputConflictList
Call-by-reference place where the information for each conflicted resource is
stored.
The function returns a list of resources that conflict and therefore cannot be selected at the
same time as resources. The conflict may be caused when resources use the same pin or the
same controller. From the MDF and CDF file information is extracted for all modules and
module types. Conflicting resources may be found even in a one-vendor D-PDU API system.
The system-integrator is responsible for any conflicting resources when MVCI Protocol
Modules belonging to different vendors are connected by a Y-cable and more than one MVCI
Protocol Module is connected to a vehicle. The application will decide which group of modules
are connected to a single vehicle. Therefore pInputModuleList will be filled correctly.
NULL. All resource conflicts of ResourceId between the modules listed in pInputModuleList are
determined. Memory for the PDU_RSC_CONFLICT_ITEM structure is allocated.
The call-by-reference variable pOutputConflictList is filled. When PDUDestroyItem is called
from the application pOutputConflictList is released.
47

Return values
the MVCI Protocol Module firmware. We
must update the MVCI Protocol Module
firmware.
PDU_ERR_INVALID_PARAMETERS Either the resource ID is invalid or one of the
reference pointers (pInputModuleList or
pOutputConflictList) are invalid (NULL).
Table 20: PDUGetConflictingResources return values
48

7.1.3.15 PDUGetModuleIds
Syntax
EXTERNC T_PDU_ERROR PDUGetModuleIds(PDU_MODULE_ITEM **pModuleIdList)
Parameters
pModuleIdList
Pointer for storing the pointer to Module Type Ids and the Module handles for
all modules that are connected to the D-PDU API.
The function returns the module type Id, module handle information, vendor specific string
information, and module status from the D-PDU API. D-PDU API assigns a handle (hMod) to
all MVCI Protocol Modules detected by the D-PDU API. The module type is given by the
ModuleTypeId. Using hMod information we can access individual modules.
When a change in the list of MVCI Protocol Modules is detected by the D-PDU API an
information callback occurs. In order to obtain the new list of available MVCI protocol modules
the client application should call PDUGetModuleIds again. The module handles (hMod) for
already detected modules are not changed.
An already connected module maintains its handle (hMod) even after the communication to
the module is lost. In this case, only after a PDUModuleDisconnect or PDUDestruct the
module handle is destroyed.
A status change shows that changes to a module connection have occurred. This happens
during PDUModuleConnect, PDUModuleDisconnect, loss of communications with a MVCI
Protocol Module and connection by another D-PDU API session.
The function validates input parameter; pointer parameter cannot be NULL.
PDU_MODULE_ITEM structure is allocated and the call-by-reference variable pModuleIdList
is filled. When calling PDUDestroyItem from the application the D-PDU API structure
(pModuleIdList) is freed.
The D-PDU API will generate a unique handle for each MVCI Protocol Module interface type
supported.
The handle is no longer valid and will be removed from the list of detected modules if detection
of a module or module interface type is lost and the handle was in the state
PDU_MODST_AVAIL. In case the module or module interface type is re-detected, a new
module handle is generated. Each time the list of module handles changes, an information
event is generated to indicate that a new list of MVCI Protocol Module handles is available.
When a MVCI Protocol Module changes status, a status event item is generated. The
following list describes each status change use case.
Use Case: Module State = PDU_MODST_AVAIL:
- Initial detection by the D-PDU API.
- For any API function calls to the module, the state must be PDU_MODST_READY
49

Use Case: Module State = PDU_MODST_UNAVAIL:
- Initial detection by the D-PDU API, but already in use by another client session
- A module may transition to PDU_MODST_UNAVAIL if the D-PDU API detects a loss
of communication to the module after being in the READY state.
Use Case: Module State Change = (PDU_MODST_AVAIL -> PDU_MODST_READY):
- The transition is made after a successful call to PDUModuleConnect.
- API session between the module and the client application can be made
- NO status event item can be generated (the function callback
(PDURegisterEventCallback) can only be called in the state PDU_MODST_READY).
Use Case: Module State Change = (PDU_MODST_READY -> PDU_MODST_UNAVAIL):
- The transition is made after a loss of communication to a module.
- All ComPrimitives currently executing (i.e. periodic) and all ComPrimitives in the CoP
queue will be cancelled (PDU_COPST_CANCELLED).
- All active ComLogicalLinks will go into the offline state (PDU_CLLST_OFFLINE).
- In the case of losing communications to a module the order of events is:
PDU_COPST_CANCELLED, PDU_CLLST_OFFLINE, and PDU_MODST_UNAVAIL.
Use Case: Module State Change = (PDU_MODST_READY -> PDU_MODST_NOT_READY):
- The transition is made when a condition occurs on the device which does not allow the
execution of any further API calls. This may not be a permanent condition (the module
recovers from the not ready state (e.g. PDU_IOCTL_RESET)).
Use Case: Module State Change = (PDU_MODST_READY -> PDU_MODST_AVAIL):
- The transition is made after a successful call to PDUModuleDisconnect.
- All resources are freed for the module.
- NO status event item is generated since further event items will not be queued for the
module.
Return values
PDU_ERR_INVALID_PARAMETERS Invalid NULL pointer for pModuleList
Table 21: PDUGetModelIds return values
50

7.1.3.16 PDULockResource
Syntax
EXTERNC T_PDU_ERROR PDULockResource(UNUM32 hMod, UNUM32 hCLL, UNUM32
LockMask)
Parameters
hMod Handle of MVCI Protocol Module.
hCLL Handle of ComLogicalLink to be granted exclusive access to it’s resource.
LockMask Bit encoded mask for type of locking request to a physical resource:
Bit 0: 1=LockPhysicalComParams
Request lock to modify physical ComParameters
Bit 1: 1=LockPhysicalTransmitQueue
Request lock for transmit operations
The function PDULockResource will give a ComLogicalLink exclusive privilege of a physical
resource. This is usefull in case of an application that needs to have the physical bus
protected from multiple ComLogicalLinks which share the physical resource. These exclusive
rights to the physical resource are allocated based on the LockMask value. Once the resource
is locked, another call of PDULockResource from a different ComLogicalLink will fail.
This locking of the resource does not affect the monitoring or receiving of messages from a
physical resource.
The function validates all input parameters. If no other locks and currently active transmissions
can be found on the resource, the status of the ComLogicalLink's resource is set. Otherwise
the value PDU_ERR_RSC_LOCKED or PDU_ERR_FCT_FAILED is returned.
Transmit Queue Lock:
- When the transmit queue is locked, this will force a SUSPEND_TX_QUEUE to all
other ComLogicalLinks sharing the physical resource.
- Any new ComLogicalLink have their ComPrimitive queue in the
SUSPEND_TX_QUEUE mode.
- A RESUME_TX_QUEUE is sent to all ComLogicalLinks sharing the physical resource
when the lock on the transmit queue is released.
- If there are any enabled tester present messages, they will be stopped when a
ComPrimitive queue is suspended.
Physical ComParameter Lock:
- Any ongoing transmissions will not be terminated by a lock on the physical
ComParameters (ComParameter ActiveBuffer)
51

- Calls to PDU_COPT_UPDATEPARAM for physical ComParameters on a second
ComLogicalLink will lead to an error event for the second ComLogicalLink
(PDU_ERR_EVT_RSC_LOCKED).
Automatic unlocking:
- If PDUDestroyComLogicalLink or PDUDisconnect are called, then an automatic
unlock will occur.
Change of lock status:
- The other ComLogicalLinks that are sharing the physical resource are informed
whenever the lock status of a resource changes through an information callback
(PDU_IT_INFO)
- The current lock state of the physical resource can be determined by a client
application by calling the PDUGetResourceStatus function.
Return values
handle is invalid
connected
PDU_ERR_RSC_LOCKED The requested resource is already in the
“locked” state
Table 22: PDULockResource return values
52

7.1.3.17 PDUUnlockResource
Syntax
EXTERNC T_PDU_ERROR PDUUnlockResource(UNUM32 hMod, UNUM32 hCLL,
UNUM32 LockMask)
Parameters
hCLL Handle of ComLogicalLink unlocking the resource.
LockMask Bit encoded mask for type of locking request to a physical resource:
Bit 0: 1=LockPhysicalComParams
Request lock to modify physical ComParameters
Bit 1: 1=LockPhysicalTransmitQueue
Request lock for transmit operations
The function PDUUnlockResource releases the lock type on the resource the ComLogicalLink
is connected to. The condition is that the lock type was previously locked by the same
ComLogicalLink.
When the function is called all input parameters are validated and the status of the
ComLogicalLink's resource is set.
Return values
PDU_ERR_PDUAPI_NOT_CONSTRUCTED D-PDU API has not been constructed
before
handle is invalid
PDU_ERR_RSC_LOCKED_BY_OTHER_CLL The requested resource is locked by a
different ComLogicalLink
connected
PDU_ERR_RSC_NOT_LOCKED The resource is already in the unlocked
state
Table 23: PDUUnlockResource return values
53

7.1.3.18 PDUCreateComLogicalLink
Syntax
EXTERNC T_PDU_ERROR PDUCreateComLogicalLink(UNUM32 hMod,
PDU_RSC_DATA *pRscData, UNUM32 resourceId, void *pCllTag, UNUM32
*phCLL, PDU_FLAG_DATA *pCllCreateFlag )
Parameters
hMod Handle of MVCI Protocol Module
pRscData This parameter defines the settings for a ComLogicalLink. It represents a
Resource DataObject.
-Unknown Resource Scheme: This parameter must always have a valid value
(cannot be NULL) and the resourceId parameter must be PDU_ID_UNDEF.
-Specific Resource Id Scheme: This parameter must be NULL and the
resourceId parameter must have a valid value.
resourceId Resource Id that maps to the resource data objects defined in the D-PDU API
Resource Table. The settings for the ComLogicalLink are based on this
information.
-Unknown Resource Scheme: This parameter must be set to
PDU_ID_UNDEF and the parameter pRscData must not be NULL.
-Specific Resource Id Scheme: This parameter must be valid and the
parameter pRscData must be set to NULL. Based on the resourceId value
resource objects are selected from the D-PDU API Resource Table.
pCllTag An Application defined tag value. Used in event callbacks as additional
information for status, errors and result events for the ComLogicalLink.
phCLL Call-by-reference place for storage of ComLogicalLink handle.
pCllCreateFlag
Call-by-reference place to store flag bits used to create a ComLogical Link
Based on a specified Resource Id the function creates a ComLogicalLink. After the logical link
was created it’s internal resources are reserved. Also the communication state is offline. This
means that no vehicle communication is performed. However, at this point the MVCI Protocol
Module hardware is ready for communication.
In order to determine conflicting resources, the MDF and CDF file content is used. Also the
D-PDU API gives a list of conflicts for a given resource (PDUGetConflictingResources) across
multiple MVCI Protocol Modules that belong to a single vendor.
A ComLogicalLink can be created either by using a specified set of resource items (bus type,
protocol, and pins) or by using a predefined resource id.
In case of an Unknown Resource Id Scheme PDUCreateComLogicalLink is called with a set of
resources for the link (protocol id, bus type id, pin ids). No checking is done in advance, if that
set of resources is supported by the device, if the resources are available or if this request
might conflict with another one.
54

Although there is no need to check for availability and conflicts, multi-connection applications
are supported. In this case PDUCreateComLogicalLink is called multiple times followed by
corresponding calls to PDUConnect. Resource requests may be reordered by the D-PDU API
implementation, so that no resource conflicts will occur.
In case of a Specific Resource Id Scheme only the predefined ResourceId is used as a
parameter of PDUCreateComLogicalLink. This ID is determined by either reading the MDF file
or by calling PDUGetResourceId. Availability and conflicts may be checked by the application
at any time by calling PDUGetResourceStatus and PDUGetConflictingResources.
In general the function PDUCreateComLogicalLink validates all input parameters; pointer
parameters cannot be NULL. The function checks if the resource is still available. In case of
availability the resource is marked as "in use" in the resource table.
If a ComLogicalLink uses PDULockResource, that link will have exclusive rights to modify the
physical ComParameters for the resource. All ComLogicalLinks, which share a physical
resource, may modify the physical ComParameters. Each ComLogicalLinks sharing a physical
resource will read the last values set, since there is only one set of physical ComParameters
at a time.
When a ComLogicalLink is created, the event status item (PDU_CLLST_OFFLINE) is not
generated. It must be assumed by the application that OFFLINE is the initial status after
creation. This is required since the event callback function has not yet been defined by the
application for the ComLogicalLink.
When a ComLogicalLink’s status changes, a status event item is generated. The status
transition between PDU_CLLST_OFFLINE and CLLST_ONLINE is related to the execution of
the API function PDUConnect and PDUDisconnect. When the status is CLLST_ONLINE a
status transition between CLLST_ONLINE and CLLST_COM_STARTED can be initiated by
executing the ComPrimitives PDU_COPT_STARTCOMM and PDU_COPT_STOPCOMM.
Important note:
In addition to the core D-PDU API functionality described above, the license check is executed
during the API function call PDUCreateComLogicalLink. In case of a missing license the
function will report an error code PDU_ERR_FUNCTION_FAILED plus special value
PDU_CLLHDL_LICENSE_CHECK_FAILED as ComLogicalLink handle. The special value is
defined in file pdu_api.h as follows:
#define PDU_CLLHDL_LICENSE_CHECK_FAILED 0x80000000
55

Return values
PDU_ERR_FCT_FAILED Function call failed or no license available
(see above)
PDU_ERR_INVALID_PARAMETERS Invalid NULL pointer for phCLL, invalid
NULL pointer for pCllCreateFlag, or invalid
resource id
PDU_ERR_RESOURCE_BUSY Resource busy. Resource already in use
connected
PDU_ERR_INVALID_HANDLE Invalid MVCI Protocol Module handle
Table 24: PDUCreateComLogicalLink return values
56

7.1.3.19 PDUDestroyComLogicalLink
Syntax
EXTERNC T_PDU_ERROR PDUDestroyComLogicalLink(UNUM32 hMod, UNUM32 hCLL)
Parameters
hCLL Handle of ComLogicalLink to be destroyed.
This function will destroy the given ComLogicalLink. All input parameters are validated. All
unread items in the ComLogicalLink’s event queue are destroyed. The ComPrimitives for the
ComLogicalLink are cancelled. No PDU_COPST_CANCELLED event is generated, because
the handle of the ComLogicalLink is no longer valid.
If PDUGetEventItem was used, the returned event item will remain “reserved” by the
application. PDUDestroyItem will release any “reserved” memory. The ComLogicalLink is
disconnected from the physical resource. The D-PDU API releases the physical resource from
the ComLogicalLink.
The hCLL handle loses its validity. During this function call no other event items will be
queued.
Shared resource behaviour
In the case of a shared resource the physical ComParameters remain unchanged. If the
sharing ComLogicalLinks are not in the PDU_CLLST_OFFLINE state, the physical resource
remains connected to the physical bus. Any lock on the physical ComParameters and/or the
physical transmit queue will be automatically removed. A change in lock status will determine
an information callback to the shared ComLogicalLinks.
Non-shared resource behaviour
If the resource is not shared by other ComLogicalLinks, then it becomes available to the whole
system (PDU_RSCST_AVAIL_NOT_IN_USE).
57

Return values
before
PDU_ERR_INVALID_HANDLE Invalid MVCI Protocol Module or
ComLogicalLink handle
connected
Table 25: PDUDestroyComLogicalLink return values
58

7.1.3.20 PDUConnect
Syntax
EXTERNC T_PDU_ERROR PDUConnect(UNUM32 hMod, UNUM32 hCLL)
Parameters
hCLL Handle of ComLogicalLink to be connected to the vehicle interface.
This function physically connects a ComLogicalLink to the vehicle interface. When the function
is called the communication state of the ComLogicalLink must be "offline". After execution, the
state changes to "online". The function must be called before executing any communication to
the vehicle ECU.
When the function is called all input parameters are validated.
ComParameters are copied from the working buffer into the active buffer. The physical
ComParameters, that have been locked, are not changed. If there are one or more physical
ComParameters, which do not match the actual list of locked physical ComParameters, an
error event item is generated for the ComLogicalLink (PDU_ERR_EVT_RSC_LOCKED).
Even in this non-matching case the ComLogicalLink will still transition to the ONLINE state.
The working table of Unique Response Identifiers is added into the active table.
ComLogicalLink filters are configured and enabled. The URID table is used for the filter
configuration, except in the case the client application has configured filters prior to
PDUConnect. This may be done by calling any of the following PDUIoctl functions:
PDU_START_MSG_FILTER, PDU_CLEAR_MSG_FILTER, and PDU_STOP_MSG_FILTER.
Any client application configuration will override any D-PDU API internal configuration using
the URID table.
Next follows the physical connection to the vehicle bus, which must not be done during
PDUConnect or when a PDU_COPT_STARTCOMM is required to obtain the physical bus
parameters.
The function call concludes with the state of the ComLogicalLink changing to
PDU_CLLST_ONLINE. Also an event is generated indicating the new state.
59

Return values
handle is invalid
PDU_ERR_CLL_CONNECTED ComLogicalLink is already in the “online”
state
connected
Table 26: PDUConnect return values
60

7.1.3.21 PDUDisconnect
Syntax
EXTERNC T_PDU_ERROR PDUDisconnect(UNUM32 hMod, UNUM32 hCLL )
Parameters
hCLL Handle of ComLogicalLink to be disconnected to the vehicle interface
The function will physically disconnect the ComLogicalLink from the vehicle interface. No more
communication to the vehicle ECU will take place. When the function is called, the state of the
ComLogicalLink must be "online" or "com_started”. After the function is executed, the
communication state changes to "offline".
When the function is called input parameters are validated. The ComLogicalLink will be set to
“disconnected” in the internal resource table, so that no other new ComPrimitives will be
initiated. The active ComPrimitives and the idle ones found in the ComPrimitive queue will be
cancelled.
The ComParameter values and ComLogicalLink filters will not be reset to their default values.
They are maintened for a future reconnection. The ComLogicalLink is physicaly disconnected
from the resource and the resource is released.
Behaviour in case of shared resources
The physical ComParameters remain unchanged, if the resource is shared by another
ComLogicalLink.
The physical resource remains connected to the physical bus, if the resource is shared by
another ComLogicalLink. This is valid only if the sharing ComLogicalLinks are NOT in the
PDU_CLLST_OFFLINE state.
The lock will automatically be removed, if the ComLogcialLink had a lock on the physical
ComParameters and/or the physical transmit queue. Any change in the lock status is indicated
to the shared ComLogicalLinks through an information callback.
61

Return values
connected
PDU_ERR_CLL_NOT_CONNECTED ComLogicalLink is not connected
Table 27: PDUDisconnect return values
62

7.1.3.22 PDUGetTimestamp
Syntax
EXTERNC T_PDU_ERROR PDUGetTimestamp(UNUM32 hMod, UNUM32 *pTimestamp)
Parameters
hMod Handle of MVCI Protocol Module for which the timestamp is to be requested.
pTimestamp Call-by-reference place for storing timestamp in microseconds.
The current time (derived directly from the hardware clock) is obtained from a MVCI Protocol
Module. Timestamps are internally generated based on the value of this time. The timestamps
are returned by PDUGetStatus and have the same unit and resolution as the hardware clock.
NULL.
The latest status information for the specified handle (Module) is returned and stored in the
memory allocated by the client application.
Return values
PDU_ERR_INVALID_PARAMETERS pTimestamp is invalid ( NULL )
PDU_ERR_COMM_PC_O_VCI_FAILED Communication between host and MVCI
connected
Table 28: PDUGetTimestamp return values
63

7.1.3.23 PDUGetComParam
Syntax
EXTERNC T_PDU_ERROR PDUGetComParam( UNUM32 hMod, UNUM32 hCLL,
UNUM32 ParamId, PDU_PARAM_ITEM **pParamItem)
Parameters
hCLL Handle of ComLogicalLink for which the ComParameter is to be requested.
ParamId ID value of the ComParam, which is to be requested. The ComParameter’s
IDs are specified in the MDF file.
pParamItem Call-by-reference place for storing the item with the requested ComParameter
from the MDF file according to the specified ParamId. The PDUDestroyItem
function will release the item from the application after use.
The function obtains from the working buffer a value for a communication or a bus
ComParameter. This value is the same as the value, that would be found in the MVCI Protocol
Module after executing all previous ComPrimitives from the ComPrimitive queue and taking
into consideration changes made by the logical link via PDUSetComParam.
NULL. Memory is allocated for the PDU_PARAM_ITEM result. The ComParameter information
is filled from the ComParameter working buffer.
Return values
before
PDU_ERR_INVALID_HANDLE MVCI Protocol Module Handle or
PDU_ERR_INVALID_PARAMETERS ComParameter ID or pointer for
pParamItem is invalid (NULL)
connected
PDU_ERR_COMPARAM_NOT_SUPPORTED ComParameter is not supported, e.g.,
because it is of type PDU_PS_ECU,
PDU_PS_OPTIONAL or
PDU_PC_UNIQUE_ID
Table 29: PDUGetComParam return values
64

7.1.3.24 PDUSetComParam
Syntax
EXTERNC T_PDU_ERROR PDUSetComParam( UNUM32 hMod, UNUM32 hCLL,
PDU_PARAM_ITEM *pParamItem)
Parameters
hCLL Handle of ComLogicalLink for which the ComParameter shall be set.
pParamItem ComParameter item structure with the ComParameter element to be set.
Obtained by calling PDUGetComParam(). Before calling this function the
structure has to be filled with the desired ComParameter value (min value,
max value and default value) by the application. This value information is
taken from the MDF file by the application.
The function transfers a ComParameter setting to the D-PDU API for the specified
ComLogicalLink. The ComParameter is stored in a working buffer ComParameter set. By
calling several times PDUSetComParam, multiple ComParameter changes can be obtained.
The working buffer ComParameter set holds all ComParameter changes. It becomes active
for the ComLogicalLink in the case PDUConnect is called or when a ComPrimitive of type
PDU_COPT_UPDATEPARAM is issued. For individual ComPrimitives a temporary set of
ComParameter changes may be used.
NULL. The parameter data are copied to the ComParameter working buffer.
Use Case: "ComLogicalLink, not connected":
- After the function call PDUConnect the information of the ComParameter working
buffer will be moved to the ComParameter active buffer.
Use Case: "ComLogicalLink, connected":
- When PDUStartComPrimitive of type PDU_COPT_UPDATEPARAM is called, the
working buffer is copied to the queued active buffer. Also the ComPrimitive is queued
in the ComLogicalLink’s internal ComPrimitive Queue.
- When the ComPrimitive starts execution (a ComPrimitive event of
PDU_COPST_EXECUTING type) the ComParameter queued active buffer will be
moved to the ComLogicalLinks active buffer.
65

- If the state of the ComLogicalLink is PDU_CLLST_COMM_STARTED and tester
present handling is activated, any change of tester present ComParameters
determines the tester present message to be sent immediately (before the initial tester
present cyclic time).
- Before any transmission the protocol handler must wait for P3Min time.
Use Case: "ComLogicalLink, connected" and ComPrimitive active with enabled
TempParamUpdate-Flag:
- The ComParameters from the working buffer are used by this ComPrimitive until the
ComPrimitive is finished; the ComParameters from the active buffer will NOT be used.
- Even if the “Active” or “Working” buffers are modified by any subsequent calls to the
PDUSetComParam function, the ComParameters for the ComPrimitive will not
change.
- When the PDUStartComPrimitive function call returns, the ComParameter Working
Buffer is restored to the Active Buffer.
- The TempParamUpdate Flag can not be used to change Physical ComParameters.
Use Case: Change of Physical BusType ComParameter:
- A PDU_PC_BUSTYPE ComParameter is of physical type. For each physical resource
there is only one set of physical ComParameters. This is why they cannot be changed
temporarily using the TempParamUpdate Flag.
- The physical ComParameters may be modified by any ComLogicalLink that shares
the physical resource.
- If PDULockResource is used by a ComLogicalLink, that ComLogicalLink will have
exclusive rights to modify the physical ComParameters for the resource. Any other
modifications brought by another ComLogicalLink, after a
PDU_COPT_UPDATEPARAM ComPrimitive, will determine the D-PDU API to
generate an error event item (PDU_ERR_EVT_RSC_LOCKED). The error event
reports, that the requested change operation is not possible.
Use Case: Change of Unique ID Type ComParameter:
- Changes to PDU_PC_UNIQUE_ID ComParameters are not allowed via the
PDUSetComParam function. Only the API functions PDUSetUniqueRespIdTable and
PDUGetUniqueRespIdTable are allowed to use this type of ComParameter.
Use Case: Change of Tester Present (PDU_PC_TESTER_PRESENT) Type
ComParameter:
- PDU_PC_TESTER_PRESENT ComParameters cannot be modified temporarily by
using the TempParamUpdate flag in the PDU_COP_CTRL_DATA data structure. After
enabling tester present handling the message is sent immediately before the initial
tester present cyclic time (CP_TesterPresentTime) expires. After the initial
transmission the periodic transmission of tester present messages begins.
66

Return values
before
PDU_ERR_COMPARAM_NOT_SUPPORTED ComParameter is not supported, (e.g. type
PDU_PC_UNIQUE_ID)
connected
PDU_ERR_INVALID_PARAMETERS One of the following invalid conditions:
-Invalid ComParameter ID
-Invalid ComParameter data structure
-pParamItem NULL pointer
-Defined ComParameter value cannot be
supported by the MVCI Protocol Module
hardware/software
Table 30: PDUSetComParam return values
67

7.1.3.25 PDUGetUniqueRespIdTable
Syntax
EXTERNC T_PDU_ERROR PDUGetUniqueRespIdTable(UNUM32 hMod, UNUM32 hCLL,
PDU_UNIQUE_RESP_ID_TABLE_ITEM **pUniqueRespIdTable)
Parameters
hCLL Handle of ComLogicalLink.
pUniqueRespIdTable
Call-by-reference place for storing the Unique Response ID Table for the
ComLogicalLink; after use PDUDestroyItem will release the item allocated by
the D-PDU API.
The function returns information of all unique response identifiers configured for the
ComLogicalLink. Each unique response identifier is associated with a list of
PDU_PC_UNIQUE_ID ComParameters.
If PDUGetUniqueRespIdTable is called before PDUSetUniqueRespIdTable, the returned
structure contains the ComParameter information for a single unique response only. In this
case the UniqueRespIdentifier is set to PDU_ID_UNDEF. Using this information the correct
set of ComParameters can be determined. This set is used by the Protocol as unique ECU
response identification.
PDUGetUniqueRespIdTable uses the same mechanisms for handling ComParameters in an
internal working table as described for PDUGetComParams. This is because the Unique
Response ID Table is a structure holding ComParameters.
PDU_PC_UNIQUE_ID ComParameters can only be used with Unique Response ID Table
functions. They cannot be used with functions PDUGetComParam() or PDUSetComParam().
NULL. The PDU_UNIQUE_RESP_ID_TABLE_ITEM structure is allocated. If the table has not
been previously set by PDUSetUniqueRespIdTable, then only one entry will be allocated. In
this case the UniqueRespIdentifier will be PDU_ID_UNDEF.
The table structure for the ComLogicalLink is filled. The table elements depend on the
selected protocol for the ComLogicalLink. The number of ComParameters in the list also
depends on the protocol. There can be one or more entries in the table.
68

Return values
PDU_ERR_PDUAPI_NOT_CONSTRUCTE
D
PDU API has not been constructed before
PDU_ERR_MODULE_NOT_CONNECTED MVCI Protocol Module not connected
PDU_ERR_INVALID_PARAMETERS Invalid pointer pUniqueRespIdTable (NULL)
Table 31: PDUGetUniqueRespIdTable return values
69

7.1.3.26 PDUSetUniqueRespIdTable
Syntax
EXTERNC T_PDU_ERROR PDUSetUniqueRespIdTable (UNUM32 hMod, UNUM32
hCLL, PDU_UNIQUE_RESP_ID_TABLE_ITEM *pUniqueRespIdTable)
Parameters
hCLL Handle of ComLogicalLink.
pUniqueRespIdTable
Call-by-reference place which contains the Unique Response ID Table for the
ComLogicalLink. The Application allocates the item.
The function sets Unique Response Id Table information for a ComLogicalLink. Any response
from a specific ECU (functional or physical responses) is uniquely defined by a set of
ComParameters contained in the response identifier. The UniqueRespIdentifier is assigned by
the application, with a valid range of 0x0 - 0xFFFFFFFF.
The table is used to define physical responses, functional responses and monitored
messages. The list of ComParameters contains all addressing type modes
(functional/physical). Thus any message from a specific ECU is mapped to a unique ECU
identifier. The UniqueRespIdentifier for an ECU variant can be used without the need for
interpretation of protocol-specific information.
PDUSetUniqueRespIdTable handles ComParameters in an internal working Buffer (the same
way PDUGetComParams does). This is because the Unique Response ID Table is a structure
holding ComParameters. When executing a PDU_COPT_UPDATEPARAM ComPrimitive via
the PDUStartComPrimitive function, the new table becomes active.
NULL. All ComParameter entries in the table must be of PDU_PC_UNIQUE_ID type.
The table for ECU Response Handling is stored in a working buffer.
Use Case: "ComLogicalLink, not connected":
- When PDUConnect is called, the Unique Response Identifer working table is moved to
the active table.
Use Case: "ComLogicalLink, connected":
- When a PDU_COPT_UPDATEPARAM ComPrimitive is executing via the
PDUStartComPrimitive function, the ComPrimitive is queued in the ComLogicalLink’s
internal ComPrimitive Queue, and a copy of the URID Table is stored in a queued
active table. For all subsequent ComPrimitives, the queued active table is used.
- When the ComPrimitive’s status changes to PDU_COPST_EXECUTING, the queued
active Unique Response Identifier table will be moved to the ComLogicalLinks active
table.
70

Return values
PDU_ERR_COMPARAM_NOT_SUPPORTED One of the ComParameters in the list is not
of the type PDU_PC_UNIQUE_ID
PDU_ERR_INVALID_PARAMETERS The pointer pUniqueRespIdTable is invalid
(NULL)
PDU_ERR_MODULE_NOT_CONNECTED MVCI Protocol Module not connected
Table 32: PDUSetUniqueRespIdTable return values
71

7.1.3.27 PDUStartComPrimitive
Syntax
EXTERNC T_PDU_ERROR PDUStartComPrimitive(UNUM32 hMod, UNUM32
hCLL, T_PDU_COPT CoPType, UNUM32 CoPDataSize, UNUM8 *pCoPData,
PDU_COP_CTRL_DATA *pCopCtrlData, void *pCoPTag, UNUM32 *phCoP )
Parameters
hCLL Handle of ComLogicalLink for which the ComPrimitive shall be started
CoPType Type of the ComPrimitive, which shall be started
CoPDataSize Size of data for the ComPrimitive; No data is supplied if the value is 0.
pCoPData Reference of the buffer holding the data; NULL in case of no supplied data
pCoPCtrlData
Pointer to the control data structure for the ComPrimitive; NULL in case of no
supplied control data. The PDU_COP_CTRL_DATA structure is not used for
the ComPrimitives of type PDU_COPT_UPDATEPARAM and
PDU_COPT_RESTORE_PARAM.
pCoPTag Application-specific tag value, that provides additional information about the
event source. The value is bound to the ComPrimitive and provided to the
application when event items are fetched from the event queue.
phCoP Call-by-reference place for storing the unique ComPrimitive handle. This
handle is assigned by the D-PDU API to the new ComPrimitive.
The function creates a ComPrimitive (used for sending/receiving data) of a given type. The
execution of the ComPrimitive is initiated and it depends on the ComPrimitive type and the
protocol implementation. The pCoPData indicates the D-PDU data to be sent. Additional
control over the execution is given by the PDU_COP_CTRL_DATA structure.
Via the call-by-reference element phCoP the ComPrimitive handle (which has been assigned
by the D-PDU API) is stored for further API function calls. The API function PDUGetStatus()
returns the ComPrimitive's status. The status can also be retrieved as an event item.
When the status of the Com Primitive is PDU_COPST_FINISHED or
PDU_COPST_CANCELLED, the D-PDU API will destroy the ComPrimitive internally and no
more result items will be queued for that ComPrimitive in the ComLogicalLink’s event queue.
Thus no more operations can be executed for the destroyed ComPrimitive (otherwise a PDU
ERROR PDU_ERR_INVALID_HANDLE is returned)
When the function is called, all input parameters are validated; required pointer parameters
cannot be NULL. The state of the resource used by the ComLogicalLink is checked. If the
resource is currently unavailable, an error is returned.
The ComPrimitive is placed into the ComPrimitive Queue. The correct set of ComParameters
is mapped to the ComPrimitive. If the flag TempParamUpdate is not set (=value 0), the
ComPrimitive uses the ComParameters from the “Active” buffer. If the flag TempParamUpdate
is set (=value 1), the ComPrimitive uses the ComParameters from the “Working” buffer
72

The ComPrimitive’s ComParameters are effective until the ComPrimitive is finished or
cancelled. Even modifications of the “Active” or “Working” buffer by function calls
PDUSetComParam or PDUStartComPrimitive with type PDU_COPT_UPDATEPARAM will not
change the active ComPrimitive’s ComParameters.
The ComPrimitive uses the UniqueRespIdTable from the “Active” table. Temporary
UniqueRespIdTables are not supported. The ComPrimitive’s UniqueRespIdTable remains
effective until the ComPrimitive is finished. Even modifications of the “Active” or “Working”
buffer by function calls PDUSetUniqueRespIdTable or PDUStartComPrimitive with type
PDU_COPT_UPDATEPARAM will not change the active ComPrimitive’s UniqueRespIdTable.
The status of ComPrimitive is set to PDU_COPST_IDLE, when it is placed in the queue.
Use Case: Initial receive handling
- The UniqueRespIdentifer table and ComParameters from the currently active
SendRecv ComPrimitive are used by the transport layer for initial receive handling of
frames/messages.
- The current active ComParameter buffer will be used, when the ComLogicalLink has
no active SendRecv ComPrimitive.
- When the frame/message is bound to a ComPrimitive, the set of ComParameters
being attached to the ComPrimitive is used for any further processing (e.g. receive
timing).
Use Case: CLL State = PDU_CLLST_OFFLINE
- This is the initial state when the ComLogicalLink is created
(PDUCreateComLogicalLink) and when the ComLogicalLink is disconnected from the
vehicle bus (via PDUDisconnect or loss of communication to a module).
- While this state is active, no ComPrimitives can be added to the ComLogicalLink
queue (result = PDU_ERR_CLL_NOT_CONNECTED).
- For ComPrimitive queueing to be allowed, the state must be PDU_CLLST_ONLINE.
Use Case: CLL State Change = (any state -> PDU_CLLST_OFFLINE)
- This state transition is made after a successful function call to PDUDisconnect or a
loss of communication to a module.
- All ComPrimitives currently executing and all ComPrimitives in the ComPrimitive
queue will be cancelled. A status event item PDU_COPST_CANCELLED is
generated for each active ComPrimitive for the ComLogicalLink.
- If communication to a module is lost, the event order is: PDU_COPST_CANCELLED,
PDU_CLLST_OFFLINE, PDU_MODST_UNAVAIL.
Use Case: CLL State Change = (PDU_CLLST_OFFLINE -> PDU_CLLST_ONLINE)
- The transition to this state is made after a successful call of the function PDUConnect.
- For vehicle protocols that require an initialization sequence, the ComLogicalLink must
be in the state PDU_CLLST_COM_STARTED to allow regular transmit operations on
the vehicle bus. In this ComLogicalLink state Receive only ComPrimitives can be
used to monitor the vehicle bus.
73

Use Case: CLL State Change = (PDU_CLLST_ONLINE -> PDU_CLLST_COM_STARTED)
- The state transition is made, when a ComPrimitive type PDU_COPT_STARTCOMM
has been executed successfully.
- If tester present handling is enabled, the message is sent immediately, before the
initial tester present cycle time. Thereafter the periodic tester present cycles begins.
- Tester Present messages are enabled in the state PDU_CLLST_COM_STARTED
only.
Use Case: CLL State Change = (PDU_CLLST_COM_STARTED -> PDU_CLLST_ONLINE)
- The state transition is made after successful execution of the ComPrimitive with type
PDU_COPT_STOPCOMM.
- When this ComPrimitive successfuly executes or when the ComLogicalLink transitions
to PDU_CLLST_OFFLINE, all ComPrimitives currently executing and all
ComPrimitives in the queue are cancelled. A status event item
PDU_COPST_CANCELLED is generated for each active ComPrimitive of the
ComLogicalLink.
Specific behaviour for status changes of ComPrimitives
Upon status changes of ComPrimitives, an event item is generated. The relevant use cases
are described in the list below:
Use Case: ComPrimitive State Change (IDLE -> EXECUTING)
- The status of the ComPrimitive is set to PDU_COPST_EXECUTING, when a
ComPrimitive is removed from the CoP Queue for execution.
- For ComPrimitives of type PDU_COPT_UPDATEPARAM the queued active buffer is
copied to the ComLogicalLinks active buffer and the state is set to
PDU_COPST_FINISHED.
- In the case, that the ComLogicalLink is in the state PDU_CLLST_COMM_STARTED
and tester present handling is enabled, any changes to one of the tester present
ComParmeters will determine the tester present message to be sent right away,
before the initial tester present cyclic time.
- The protocol handler must always wait the defined P3Min time, until transmit
Operation is allowed.
- For ComPrimitives of type PDU_COPT_RESTORE_PARAM, the active buffer is
copied to the working buffer and the state is set to PDU_COPST_FINISHED
immediately.
- If the length of a ComPrimitive’s data can not be handled by the protocol, an error
event PDU_ERR_EVT_PROT_ERR is generated and the ComPrimitive’s state will
change to FINISHED. A protocol handler may use defined ComParameters to validate
a ComPrimitive’s size in advance. In this case it would reject a ComPrimitive due to
the PDU data’s length.
74

Use Case: ComPrimitive State Change (EXECUTING -> WAITING)
- When a periodic send ComPrimitive has finished each of it’s periodic cycles, it will
transition to the state PDU_COPST_WAITING.
Use Case: ComPrimitive State Change (WAITING -> EXECUTING)
- When a periodic send ComPrimitive starts it’s next transmission cycle, it will transition
to the state PDU_COPST_EXECUTING.
Use Case: ComPrimitive State Change (EXECUTING -> FINISHED)
- When a ComPrimitive has finished it’s execution, it will transition to the state
PDU_COPST_FINISHED.
- A periodic send ComPrimitive will transition to the FINISHED state after it’s last send
cycle (for NumSendCycles > 1, but not infinite [-1] ).
- A ComPrimitive will always transition to the FINISHED state after completion of it’s
operation - independent if successfuly or unsuccessfuly.
Use Case: ComPrimitive State Change (any state -> CANCELLED)
- A ComPrimitive will transition to the PDU_COPST_CANCELLED state when:
o The function PDUDisconnect was called for the ComLogicalLink.
o The function PDUDestroyComLogicalLink was called for the ComLogicalLink.
o The function PDUCancelComPrimitive was called for the ComPrimitive.
o A ComPrimitive of type PDU_COPT_STOPCOMM has completed and there
were other ComPrimitives currently executing or in the ComPrimitive queue.
Return values
PDU_ERR_TX_QUEUE_FULL The ComLogicalLink’s transmit queue is full
and thus the ComPrimitive could not be
queued
PDU_ERR_RSC_LOCKED_BY_OTHER_CLL The ComLogicalLink's resource is currently
locked by another ComLogicalLink
PDU_ERR_INVALID_PARAMETERS Either invalid NULL pointer for phCoP,
pCopData or pCopCtrlData, or the expected
response structure for a ComPrimitive with
(NumReceiveCycles != 0) is NULL or has 0
entries
75

PDU_ERR_TEMPPARAM_NOT_ALLOWED Physical ComParameters cannot be
changed as a temporary ComParam
connected
PDU_ERR_CLL_NOT_STARTED Communication has not been started on the
ComLogicalLink yet. Thus a Send
ComPrimitive cannot be accepted in this
state
Table 33: PDUStartComPrimitive return values
76

7.1.3.28 PDUCancelComPrimitive
Syntax
EXTERNC T_PDU_ERROR PDUCancelComPrimitive(UNUM32 hMod, UNUM32 hCLL,
UNUM32 hCoP)
Parameters
hCLL Handle of ComLogicalLink
hCoP Handle of the ComPrimitive, which shall be cancelled
The function cancels the operation being executed currently for the defined ComPrimitive.
When the function is called input parameters are validated. Then the ComPrimitive is removed
from the ComPrimitive Queue. The status of ComPrimitive is set to
PDU_COPST_CANCELLED. If the status of the ComPrimitive is already
PDU_COPST_FINISHED, the function will return with success.
Return values
PDU_ERR_INVALID_HANDLE MVCI Protocol Module handle,
ComLogicalLink handle or ComPrimitive
handle is invalid
connected
Table 34: PDUCancelComPrimitive return values
77

7.1.3.29 PDUGetEventItem
Syntax
EXTERNC T_PDU_ERROR PDUGetEventItem(UNUM32 hMod, UNUM32 hCLL,
PDU_EVENT_ITEM **pEventItem)
Parameters
hMod Handle of the MVCI Protocol Module, for which the event item shall be
retrieved. If a system event item shall be retrieved, the parameter is set to
PDU_HANDLE_UNDEF and the hCLL handle is ignored.
hCLL Handle of the ComLogicalLink for which the event item shall be retrieved; the
value PDU_HANDLE_UNDEF is used, if an item shall be retrieved for the
MVCI Protocol Module.
pEventItem Call-by-reference place for storing the pointer to the event item corresponding
to the defined event, hMod and hCLL. NULL is returned, if no result item is
available.
The function returns an event item data (PDU_EVENT_ITEM) for the specified event source.
In order to identify the event source PDUEventItem uses a reference of an MVCI Protocol
Module or ComLogicalLink as input parameter. Based on the returned event item, the
application evaluates the item type. Then it can access the item-specific data.
NULL. The memory for the PDU_EVENT_ITEM data is allocated and the event item
information is filled for the specified handle (Module or ComLogicalLink). The event item is
allocated and managed by the D-PDU API.
Thereafter the event item entry is removed from the queue. However, the memory for the item
remains allocated. The function call PDUDestroyItem() is used to destroy the item.
78

Return values
PDU_ERR_CLL_NOT CONNECTED ComLogicalLink is not connected
PDU_ERR_INVALID_PARAMETERS Invalid NULL pointer for pEventItem
connected
PDU_ERR_EVENT_QUEUE_EMPTY No more event items are available
Table 35: PDUGetEventItem return values
79

7.1.3.30 PDUDestroyItem
Syntax
EXTERNC T_PDU_ERROR PDUDestroyItem( PDU_ITEM *pItem)
Parameters
pItem Pointer to the item, which shall be destroyed
The function destroys the defined item, which can be of any D-PDU API item type (the item
data type has to be casted appropriately).
NULL. The type of the item, which shall be destroyed, is validated too. Thereafter the reserved
memory of the item is released by the D-PDU API.
Return values
PDU_ERR_INVALID_PARAMETERS Invalid item type or the pItem parameter is
NULL
Table 36: PDUDestroyItem return values
80

7.2 IOCTL commands
7.2.1 Overview
The table below lists all IOCTL commands for the D-PDU API function PDUIoctl and gives a
short description. For details please refer to the D-PDU API specification [ISO 22900-2 –
9.5.1].
IOCTL short name Purpose
PDU_IOCTL_RESET Reset the MVCI Protocol Module
PDU_IOCTL_CLEAR_TX_QUEUE Clear the ComLogicalLink’s transmit queue
PDU_IOCTL_SUSPEND_TX_QUEUE Suspend the ComLogicalLink’s transmit queue and stop the
queue processing. This may be helpful when filling up a
ComLogicalLink's queue with ComPrimitives.
PDU_IOCTL_RESUME_TX_QUEUE Resume the ComLogicalLink’s transmit queue and start the
queue processing
PDU_IOCTL_CLEAR_RX_QUEUE Clear the ComLogicalLink’s event queue
PDU_IOCTL_READ_VBATT Read the battery voltage on pin 16 of the MVCI module
PDU_IOCTL_SET_PROG_VOLTAGE Set the programmable voltage on the defined DLC connector pin
(resource). In the InputData (PDU_DATA_ITEM) the voltage and
pin information are specified.
PDU_IOCTL_READ_PROG_VOLTAGE Read the programmable voltage
PDU_IOCTL_GENERIC Provides the functionality to exchange generic data between
application and MVCI module. Thus supplier specific MVCI
module functionality can be controlled.
PDU_IOCTL_SET_BUFFER_SIZE Sets the buffer size limit
PDU_IOCTL_START_MSG_ FILTER Starts filtering of received messages on the defined
ComLogicalLink.
PDU_IOCTL_STOP_MSG_FILTER Stops the defineded filter
PDU_IOCTL_CLEAR_MSG_FILTER Clears all defined message filters for the specific ComLogicalLink
PDU_IOCTL_SET_EVENT_QUEUE_
PROPERTIES
Sets parameters for a ComLogicalLink’s event queue
PDU_IOCTL_GET_CABLE_ID Get the cable Id information of the cable, which is currently
connected to the MVCI module
PDU_IOCTL_SEND_BREAK Generates a UART break signal on the defined ComLogicalLink
PDU_IOCTL_READ_IGNITION_SENSE_STATE Reads the current ignition sense state from the defined pin on the
vehicle connector
Table 37: D-PDU API IOCTL commands
81

7.2.2 Details
The D-PDU API IOCTL commands are described in detail in the D-PDU API specification [ISO
22900-2 – 9.5.1].
7.2.2.1 PDU_IOCTL_RESET
This command is used to reset the MVCI Protocol Module with the specified handle. The
handle is used as a parameter in the PDUIoctl() function. The command is executed
synchronously (returns after finishing the reset procedure).
InputData: NULL
OutputData: NULL
When the command is used:
All activities currently being executed by the MVCI Protocol Module are cancelled
(without proper termination).
All existing ComLogicalLinks are suspended and receive and transmit queues are
cleared.
All associated ComPrimitives and received data items are destroyed.
All existing ComLogicalLinks are destroyed.
All hardware properties of the MVCI Protocol are reset to the default settings.
After the command has finished, the MVCI Protocol Module is in initial state with a timestamp
base being reset to zero.
The command will not affect the resource table which is set up after the start up of the module.
Because of this fact, the a PDUConstruct function call is not necessary after a reset command.
Return Value Description
PDU_STATUS_NOERROR Function call successful.
PDU_ERR_PDUAPI_NOT_CONSTRUCTED D-PDU API construct has not been called
before
PDU_ERR_FCT_FAILED Reset command failed
Table 38: PDU_IOCTL_RESET return values
82

7.2.2.2 PDU_IOCTL_CLEAR_TX_QUEUE
This command is used to clear the transmit queue of the ComLogicalLink with the handle
being passed as parameter to the PDUIoctl() function.
All ComPrimitive items are destroyed internally in the D-PDU API.
If destroyed ComPrimitive items are being called by the application an error will be
reported.
InputData: NULL
OutputData: NULL
The command PDU_IOCTL_SUSPEND_TX_QUEUE shoud be executed before
PDU_IOCTL_CLEAR_TX_QUEUE in order to avoid an overlapping of operations of queue
processing and queue clearing.
before
PDU_ERR_INVALID_HANDLE Invalid ComLogicalLink handle
Protocol Module failed
Table 39: PDU_IOCTL_CLEAR_TX_QUEUE return values
83

7.2.2.3 PDU_IOCTL_SUSPEND_TX_QUEUE
This command is used to suspend the transmit queue's processing for the ComLogicalLink
with the handle, which has been passed as parameter to the PDUIoctl() function.
InputData: NULL
OutputData: NULL
If the command is executed before a PDU_IOCTL_RESUME_TX_QUEUE command, a steady
processing of ComPrimitives can be achieved by filling up the ComLogicalLink's queue with
ComPrimitives to be processed sequentially with minimum time delay.
before
PDU_ERR_INVALID_HANDLE ComLogicalLink handle is invalid
Table 40: PDU_IOCTL_SUSPEND_TX_QUEUE return values
84

7.2.2.4 PDU_IOCTL_RESUME_TX_QUEUE
This command is used to resume the transmit queue's processing for the ComLogicalLink with
the handle, which has been passed as parameter to the PDUIoctl() function.
InputData: NULL
OutputData: NULL
PDU_ERR_PDUAPI_NOT_CONSTRUCTED D-PDU API construct has not been called before
PDU_ERR_COMM_PC_TO_VCI_FAILED Communication between host and MVCI Protocol
Module was not successful
Table 41: PDU_IOCTL_RESUME_TX_QUEUE return values
85

7.2.2.5 PDU_IOCTL_CLEAR_RX_QUEUE
This command is used to clear the event queue for the ComLogicalLink, which handle is
passed as an input parameter to the PDUIoctl() function.
All event items in the event queue of the ComLogicalLink are cleared and
automatically destroyed. These event items are result data, information about errors or
status changes.
PDUDestroyItem is internally called by the D-PDU API for each item in the event
queue.
InputData: NULL
OutputData: NULL
before
Table 42: PDU_IOCTL_CLEAR_RX_QUEUE return values
86

7.2.2.6 PDU_IOCTL_READ_VBATT
This command is used to read the voltage on pin 16 of the MVCI Protocol Module's connector.
The handle is used as a parameter of the PDUIoctl() function. The voltage is written to the
UNUM32 value (4 data bytes) of the PDU_DATA_ITEM structure. It is used as InputData by
reference.
InputData: NULL
OutputData: Value settings for PDU_DATA_ITEM
ItemType PDU_IT_IO_UNUM32
pData UNUM32 Vbat_mv; /* vehicle battery in mv */
PDU_ERR_PDUAPI_NOT_CONST
RUCTED
D-PDU API construct has not been called before.
PDU_ERR_INVALID_HANDLE MVCI Protocol Module handle is not valid.
PDU_ERR_COMM_PC_TO_VCI_F
AILED
Communication between host and MVCI Protocol
Module was not successful.
PDU_ERR_INVALID_PARAMETER
S
At least one of the parameters is invalid (pInputData
and/or pOutputData)
PDU_ERR_FCT_FAILED Command failed.
Table 43: PDU_IOCTL_READ_VBATT return values
87

7.2.2.7 PDU_IOCTL_SET_PROG_VOLTAGE
This command is used to set the programmable voltage on the specified Pin of the DLC
connector. The handle is used as a parameter of the PDUIoctl() function.
PDU_DATA_ITEM contains information about the voltage and pin. PDU_DATA_ITEM is
passed as InputData.
Valid range of values is: 5000mV - 20000mV (limited to 100 mA with a resolution of +/-100
millivolts).
InputData: Value settings for PDU_DATA_ITEM
ItemType PDU_IT_IO_PROG_VOLTAGE
pData pointer PDU_IO_PROG_VOLTAGE_DATA structure
OutputData: NULL
PDU IOCTL programming voltage description
Coded value of voltage Meaning
0x00001388 – 0x00004E20 5000 mV – 20000 mV
0xFFFFFFFE SHORT_TO_GROUND (zero impedance)
0xFFFFFFFF VOLTAGE_OFF (high impedance)
PDU_ERR_PDUAPI_NOT_CONS
TRUCTED
PDU_ERR_INVALID_HANDLE MVCI Protocol Module or ComLogicalLink handle is
invalid.
PDU_ERR_INVALID_PARAMETE
RS
and/or pOutputData)
PDU_ERR_RESOURCE_BUSY Resource is busy; the application has to execute the
command again.
PDU_ERR_VOLTAGE_NOT_SUP
PORTED
The voltage is not supported by the MVCI Protocol
Module.
PDU_ERR_COMM_PC_TO_VCI_
FAILED
PDU_ERR_MUX_RSC_NOT_SUP
PORTED
The specified pin / Resource are not supported by the
MVCI Protocol Module.
Table 44: PDU_IOCTL_SET_PROG_VOLTAGE return values
88

7.2.2.8 PDU_IOCTL_READ_PROG_VOLTAGE
This command is used to read the feedback of the programmable voltage from the voltage
source. The voltage source is set by the command PDU_IOCTL_SET_PROG_VOLTAGE. The
MVCI Protocol Module handle is passed as parameter to the PDUIoctl() function.
The PDU_DATA_ITEM structure passed as InputData by reference contains the voltage
written as an UNUM32 value (4 data bytes).
InputData:
pData UNUM32 ProgVoltage_mv; /* programming voltage in mv */
PDU_ERR_PDUAPI_NOT_CONS
TRUCTED
PDU_ERR_INVALID_HANDLE MVCI Protocol Module or ComLogicalLink handle is
invalid.
FAILED
RS
and/or pOutputData).
Table 45: PDU_IOCTL_READ_PROG_VOLTAGE return values
89

7.2.2.9 PDU_IOCTL_GENERIC (currently not supported)
A generic message is sent by the application to its drivers, passing the Data buffer down to the
associated MVCI Protocol Module hardware. The message is neither intercepted nor
interpreted.
The PDU_DATA_ITEM structure has the element "Data" as a free form buffer of bytes. The
structure is passed as InputData by reference.
ItemType PDU_IT_IO_BYTEARRAY
pData pointer PDU_IO_BYTEARRAY_DATA structure
OutputData: NULL
PDU_ERR_INVALID_PARAMETERS At least one of the parameters is invalid (pInputData
PDU_ERR_COMM_PC_TO_VCI_FAILE
D
Table 46: PDU_IOCTL_GENERIC return values
90

7.2.2.10 PDU_IOCTL_SET_BUFFER_SIZE (currently not supported)
This command sets the maximum buffer size of the received PDU on a ComLogicalLink. Its
value is specified in the UNUM32 value (4 data bytes) of the PDU_DATA_ITEM structure
being passed as InputData by reference.
ItemType PDU_IT_ IO_UNUM32
pData UNUM32 MaxRxBufferSize; /* maximum size of a received PDU for the
ComLogicalLink */
OutputData: NULL
RS
FAILED
Table 47: PDU_IOCTL_SET_BUFFER_SIZE return values
91

7.2.2.11 PDU_IOCTL_START_MSG_FILTER
This command starts filtering incoming messages for the specified ComLogicalLink.
Each ComLogicalLink can support a minimum of 64 filters.
All the defined message filters of a ComLogicalLink are deleted by calling
PDUDestroyComLogicalLink
Only when the ComLogicalLink is in PDU_CLLST_ONLINE state the filtering becomes
active.
If there are no filters configured by the application, the D-PDU API automatically
determines a set of filters by using the PDU_PC_UNIQUE_ID ComParameters
configured for the ComLogicalLink.
If there are filters set by the application using the IOCTL filter commands they will
override any filters internally configured by the D-PDU API.
All Protocols:
Pass filters and block filters will be applied to all received messages, but not to
indications or loopback messages.
Messages that match a pass filter can still be blocked by a block filter.
For ISO 15765:
Pass filters and block filters are applied to CAN ID filtering, but not to indications or
loopbacks of CAN IDs.
The UniqueRespIdTable is used for USDT/UUDT frame handling plus flow control and
extended address handling.
ItemType PDU_IT_ IO_FILTER
pData pointer PDU_IO_FILTER_LIST structure
OutputData: NULL
RUCTED
PDU_ERR_INVALID_HANDLE ComLogicalLink handle is invalid.
AILED
Module was not sucessful.
RS
Table 48: PDU_IOCTL_START_MSG_FILTER return values
92

7.2.2.12 PDU_IOCTL_STOP_MSG_FILTER
This command removes the specified filter from the ComLogicalLink.
pData UNUM32 FilterNumber; /* Filter Number to stop */
OutputData: NULL
RUCTED
AILED
RS
and/or pOutputData) or the Filter Number is invalid.
Table 49: PDU_IOCTL_STOP_MSG_FILTER return values
93

7.2.2.13 PDU_IOCTL_CLEAR_MSG_FILTER
This command removes all message filters from the ComLogicalLink.
InputData: NULL
OutputData: NULL
PDU_ERR_PDUAPI_NOT_CONSTRUCT
ED
D-PDU API construct has not been called
before.
Protocol Module was not successful.
Table 50: PDU_IOCTL_CLEAR_MSG_FILTER return values
94

7.2.2.14 PDU_IOCTL_SET_EVENT_QUEUE_PROPERTIES (currently not supported)
This command sets the properties of the ComLogicalLink event queue.
There are two properties associated with an event queue:
- the event queue size
- the queuing mechanism to be used
The command must be used before calling the PDUConnect function. A
PDU_ERR_CLL_CONNECTED error will be returned by the function if the ComLogicalLink is
already connected.
In case of the ComLogicalLink reaches the maximum size of the event queue the behaviour of
the queuing mechanism is set by the queue mode.
There are three types of queue modes:
Queue Mode Type Description
Unlimited Mode This is the Default Mode for the ComLogicalLink. Memory is allocated
for every item being placed on the event queue. The QueueSize is
ignored.
Limited Mode The ComLogicalLink’s event queue has a maximum size. When this
value is reached no new items will be placed on the event queue and
the new items are discarded.
Circular Mode When the maximum size of the ComLogicalLink’s event queue is
reached, then the oldest event item in the queue is deleted. In this way
the new event items will be placed in the event queue.
PDU_EVT_DATA_LOST event is generated when the maximum size of the ComLogicalLink’s
event queue is reached and no result items are created. This means that no PDU_IT_ERROR
items are placed on the event queue.
ItemType PDU_IT_ IO_EVENT_QUEUE_PROPERTY
pData pointer PDU_IO_EVENT_QUEUE_PROPERTY_DATA structure
OutputData: NULL
PDU_ERR_PDUAPI_NOT_CONSTRUCTE
D
PDU_ERR_INVALID_HANDLE Invalid ComLogicalLink handle.
PDU_ERR_CLL_CONNECTED ComLogicalLink is already in the “online” state.
PDU_ERR_INVALID_PARAMETERS At least one of the parameters is invalid
(pInputData and/or pOutputData).
Table 51: PDU_IOCTL_SET_EVENT_QUEUE_PROPERTIES return values
95

7.2.2.15 PDU_IOCTL_GET_CABLE_ID (currently not supported)
This command informs the application which cable is currently connected to a MVCI Protocol
Module.
InputData: NULL
pData UNUM32 CableId; /* Cable Id from CDF */
Having the cable ID, from the CDF file more information can be obtained, like short name,
description and DLCType (connector type).
PDU_ERR_PDUAPI_NOT_CONSTR
UCTED
PDU_ERR_CABLE_UNKNOWN Cable is unknown.
PDU_ERR_NO_CABLE_DETECTED No cable is detected.
PDU_ERR_COMM_PC_TO_VCI_FAI
LED
PDU_ERR_INVALID_PARAMETERS At least one of the parameters is invalid (pInputData
PDU_ERR_FCT_FAILED The MVCI Protocol Module doesn’t support cable
detection.
Table 52: PDU_IOCTL_GET_CABLE_ID return values
96

7.2.2.16 PDU_IOCTL_SEND_BREAK (currently not supported)
This command is used to send a break signal on the ComLogicalLink.
This type of signal can only be sent on certain physical layers. A PDU_ERR_FCT_FAILED is
returned if the link does not support the break feature.
- UART Break signals are longer than the time it takes to send a complete byte plus
Start, Stop and Parity bits and are caused by sending continuous (0) values (no Start
or Stop bits). In case the UART cannot distinguish between a Framing Error and a
Break, the Framing Error detection is used to identify Breaks.
- The timing of the transition from active to passive determine a SAE J1850 Break
signal and must be longer than 240µs. No maximum length is specified but it must not
be excessively long.
The ComLogicalLink's handle is passed as a parameter to the PDUIoctl() function.
InputData: NULL
OutputData: NULL
PDU_ERR_PDUAPI_NOT_CONSTRUCT
ED
D-PDU API construct has not been called
before.
Protocol Module was not successful.
Table 53: PDU_IOCTL_SEND_BREAK return values
97

7.2.2.17 PDU_IOCTL_READ_IGNITION_SENSE_STATE
This command is used to read the Switched Vehicle Battery Voltage (Ignition on/off) pin (pin
number is 24 of the MVCI module chassis connector for ISO 22900-1) and determine the state
of the ignition switch.
If the DLC pin number is 0 it means that the Switched Vehicle Battery Voltage will be read
from the MVCI Protocol Module pin 24 and not from a DLC pin.
In order to determine the state of the ignition the permanent positive battery voltage from the
vehicle is first read (UBATvehicle (pin 16 on the DLC)) and then the specified switched vehicle
battery voltage pin. Ignition ON will be +/- 2 volts of the permanent vehicle battery voltage
pData UNUM32 DLCPinNumber; /* Pin number of the vehicles data link
connector which contains the vehicle switched
battery voltage. If DLCPinNumber = 0, then
the ignition sense is routed to pin 24 of the
MVCI Protocol Module*/
pData UNUM32 IgnitionState; /* Evaluated state of switched vehicle
battery voltage.
0 = Ignition OFF
1 = Ignition ON*/
RUCTED
AILED
RS
Table 54: PDU_IOCTL_READ_IGNITION_SENSE_STATE return values
98

7.3 Data types and structures
The D-PDU API data types and structures are described in detail in the D-PDU API
specification [ISO 22900-2 – 11.1]. For additional information of D-PDU API applications with
data types, structures and error codes, see the PDUAPI_DemonstratorPDU_API.h headerfile.
7.4 Limitations
The table below lists the functionality and limitations of the Softing D-PDU API implementation.
Functionality Support and Limitations Notes
Supported VCIs Softing EDICcard2, EDICpci, EDUCusb, EDICblue,
EDICwlan, EDICnet
Softing CANcard2, CAN-AC2-PCI, CAN-PRO2-
PCIE, CANusb
Number of VCIs per
system
Unlimited Number depends on system memory
and performance
Supported protocols KWP2000 on CAN
KWP2000 on K-Line
ISO UDS on CAN
ISO RAW CAN
ISO OBD on CAN
ISO OBD on K-Line
For more information to the
supported protocols see the
corresponding protocol
documentation.
Number of multiple
parallel
ComLogicalLinks per
VCI and BusType
32 ComLogicalLinks for CAN protocols per can bus
1 ComLogicalLink for K-Line protocols per UART
The ISO RAW CAN protocol only
supports 16 ComLogicalLinks
Number of multiple
parallel
ComPrimitives per
ComLogicalLink
Not supported
Table 55: D-PDU API implementation limitations
99

100
The table below lists restrictions of the current D-PDU API implementation.
Functionality Restrictions of current implementation
IOCTL commands The following IOCTL commands are not supported:
• PDU_IOCTL_SET_BUFFER_SIZE
• PDU_IOCTL_GET_CABLE_ID
• PDU_IOCTL_START_MSG_FILTER,
PDU_IOCTL_STOP_MSG_FILTER,
PDU_IOCTL_CLEAR_MSG_FILTER
• PDU_IOCTL_SET_EVENT_QUEUE_PROPERTIES
• PDU_IOCTL_SEND_BREAK
• PDU_IOCTL_GENERIC
• PDU_IOCTL_CLEAR_RX_QUEUE
Message Filtering Message filtering is not supported by the Softing D-PDU API.
ComPrimitive types and handling Periodic ComPrimitives currently not supported by the Softing D-PDU API.
Expected response handling PDU_ID_UNDEF-URID not yet fully supported by the Softing D-PDU API
MVCI module management Removing and inserting of VCI module during runtime not supported; use
PDUDestruct and PDUConstruct after changes of modules.
Raw mode Raw mode is only supported for the ISO RAW CAN protocol.
Raw mode is currently not supported for diagnostic protocols.
Table 56: D-PDU API implementation restrictions

8 ComParameter reference
Communication protocols
The current implementation of the Softing D-PDU API software for VCIs supports the following
communication protocols:
Protocol Protocol short name
KWP2000 on CAN ISO_14230_3_on_ISO_15765_2
KWP2000 on Kline ISO_14230_3_on_ISO_14230_2
ISO UDS on CAN ISO_15765_3_on_ISO_15765_2
ISO RAW CAN ISO_11898_RAW
ISO OBD CAN ISO_OBD_on_ISO_15765_4
ISO OBD on Kline ISO_OBD_on_K_Line
Table 57: Protocol support
For more information about the supported ComParamaters for these protocols, see the
documentation of the protocols.
101

9 Demo and test application
Note: In case of trouble during application programming a trace mechanism can be activated.
9.1 Demo application
To effectively support application programmers a demo application with source code is
included in the D-PDU API software distribution. The demo application includes source code
and workspace files for Microsoft Visual Studio 2005. The files are located in the subdirectory
.PDUAPI_Demonstrator of the installation directory. The table below lists all related files:
File name Description
PDU_API.H Headerfile for D-PDU API applications with
data types, structures and error codes
PDUAPI_Demonstrator.cpp Demonstrator source code
PDUAPI_Demonstrator.vcproj Microsoft Visual studio project file
PDUAPI_WRAPPER.H Wrapper file for D-PDU API applications with
API function prototypes (Headerfile)
PDUAPI_Wrapper.cpp Wrapper file for D-PDU API applications with
API function prototypes (Sourcefile)
Table 58: Demo application files
To use the project please execute the following steps:
Make sure that the D-PDU API software is installed
Make sure that a supported VCI is installed
Make sure that a valid license is available (license file and licensed hardware)
Make sure that Microsoft Visual Studio 2005 is installed
Start Microsoft Visual Studio 2005
Load the Demonstrator project (PDUAPI_Demonstrator.vcproj)
Adapt the variable “UsedModuleIndex” at PDUAPI_Demonstrator.cpp to select the
hardware interface to be used
Build the PDUAPI_Demonstrator project
Execute the PDUAPI_Demonstrator project
A command line window will appear; please enter the D-PDU API version which you
want to use; use debugging functionalities of Visual Studio for detailed analysis
102

9.2 Interactive test application
The D-PDU API Test Application is an API frontend tool for the customer, which allows using
the API with the D-PDU API module without programming. Thus it can be used to verify the
behaviour of a D-PDU API Module, e.g. during system integration by sending and receiving of
PDU data.
The current version includes the following dialogues:
- PduApiTest (Main) dialog
- Logical-Link dialog(s)
- UniqueResponseIdTable dialog
- ComParameter dialog
- Transmit Flags dialog
- About Softing dialog
Figure 9: D-PDU API test application
103

104
How to use the D-PDU API test application described step by step:
1. The first step is to select the PDU-API Version using the combobox “Select PDU API
Version”. This is a way to test if the VCI module plus D-PDU API software was properly
installed. No error should appear in the log.
2. Next follows the parsing of the MDF file. The MVCI Module Description File (MDF)
describes all ComParameters, I/O controls, bus types, protocols and resources supported by a
specific MVCI Protocol Module. In addition, if the D-PDU API implementation supports more
than one type of MVCI Protocol Modules, the MDF may list and describe all supported
modules. All definitions of ComParameters, bus types, protocols, etc., inside the configuration
description files may be shared among the module definition in the same file. Please press the
button “Parse MDF file” to activate the parsing process.
If the MDF.xml file of the tested module is correct and the parsing of the MDF.xml file is
completed successfuly the “Select MVCI Module” combobox is filled with the PDU-API
modules (VCI module names).
All detected VCI modules currently connected to the PC are listed in the “Selected MVCI
Module” combobox of the main dialog.
For the selected D-PDU API the path of the corresponding PDUAPI.dll, MDF.xml and CDF.xml
files are displayed in the log window of the main dialog.
If the pdu_api_root.xml is not found or an error occurred (e.g. the path of the selected
module’s MDF file is not correct), the parsing will not suceed and an error message is
displayed in the log window of the dialog.
An example of a pdu_api_root.xml can be found in 12.6.
3. Now choose the interface which shall be connected and click on the “PDUModuleConnect”
button. The D-PDU API function PDUModuleConnect [ISO_22900_2 – 9.4.29] will be
executed.
4. After the successful execution of PDUModuleConnect with no errors in the log window the
“Select Protocol”, “Select Bustype” and the “Select DLC Pin(s)” comboboxes will be filled out
with the resources of the current selected module.
Choose the desired protocol, bustype and DLC Pin(s) which shall be used to create the
Logical Link.
The number of matching resource IDs must be at least 1 in order to be able to create a
LogicalLink. This number is displayed in the log window. If no matching resource ID is found,
please adjust the settings in the comboboxes MVCI module, protocol, bustype and pins
accordingly.

5. Press ”Open Loli” to create a ComLogicalLink. The LogicalLink dialog opens.
Figure 10: D-PDU API test application-Open Logical Link
Edit PDU data for the
ComPrimitives
CycleTime parameter for
ComPrimitves
ComPrimitive buttons
NumSendCycles
NumReceiveCycles
List of started
ComPrimitives
6. ”Edit Loli Params” allows the user to modify the value of a ComLogicalLink’s
ComParameter (=ComParam). Each ComParameter is individually selected and modified. Set
Param is used to validate the modified value. The value must be in the range specified by the
standard [ISO_22900_2 – B.5].
A complete set of ComParameter values for the current LogicalLink can be saved to a file
using the “Save” button. Another option is to load a ComParameter file. If the PduApiTest.ini
file is found and contains parameters for the current protocol the values are loaded, otherwise
the operation is aborted and one or more error messages are added in the log window of the
Logical-Link dialog.
If the ComParameter values found in the ini file are correct, the Protocol ComParameters array
is updated with these values. In case of errors the Protocol ComParameters array values are
105

not changed and one or more error messages are displayed in the LogicalLink dialog’s log
window.
The latest used ComParameter values for the current protocol are saved automatically in the
pduapitest.ini file when the Logical-Link dialog is closed.
Figure 11: D-PDU API test application-Edit ComParameters
7. The Unique Response ID table is a structure holding ComParameters, which are required
to uniquely identify a connection to an ECU. They typically contain addressing information like
CAN identifiers or source/target addresses. For details please see Table 59: Communication
Parameters. Each Unique Response Identifier is associated with a set of ComParameters of
type PDU_PC_UNIQUE_ID, used to uniquely define an ECU response.
For each protocol there is a different set of URID tables that can be loaded. The URID table
values in the pduapitest.ini file will be updated when the Logical-Link dialog is closed.
Figure 12: D-PDU API test application- Edit URID Table
106

Getting the URID tables:
- If the pduapitest.ini file is found and contains URID table entries for the current
protocol, then the current URID tables will be displayed in the “Edit URID Table”
dialog, else a error message is added in the log window of the Logical-link.
- If no URID table was set in the D-PDU API, the returned table has UNDEF values.
- If a valid URID table was set in the D-PDU API, then the returned tables have to be
identical with the ones that were previously set.
Setting the URID tables:
- During the initialization of the Logical-Link dialog, if a valid URID table is found in the
pduapitest.ini file then this table will be set, otherwise the default URID table will be
set.
- The URID tables in the D-PDU API can be updated each time the “Edit URID Table”
dialog is closed with OK and no error was found in the tables. After the “Edit URID
Table” dialog is closed the edited URID table will be copied and the new URID data
structure is created.
- The new URID table is set with the PDUSetUniqueRespIdTable function, and the
result is displayed in the log window.
Editing the URID tables:
- Each URID table identifier and parameter value can be edited
- If an invalid URID table identifier or parameter value is edited an error message is
generated.
- New URID tables and parameters can be added in the tree control using right-click
context menus.
- The existing URID and parameters can be removed from the tree control with a right
mouse click.
- The tables in the tree control can be saved in files with a click on the “Save” button.
- The URID tables can be loaded from a file with a click on the “Load” button.
- On Cancel the URID tables are not set in the D-PDU API.
Figure 13: D-PDU API test application-URID Table
107

These are the possible ComParameters that can be found in an URID table for CAN
diagnostics.
ComParam Description
CP_CanPhysReqFormat CAN Id format for a physical request.
Also it is used for Flow Control Can transmission. The first entry in
the URID table is default for a physical request
CP_CanPhysReqId CAN Id for physical request.
CP_CanPhysReqExtAddr Can extended address for physical request.
CP_CanRespUSDTFormat CAN Id format for a USDT response.
Usage: response handling
CP_CanRespUSDTId CAN Id for a USDT response.
Usage: response handling. Set the value to 0xFFFFFFFF, if the
ComParameter shall not be used.
CP_CanRespUSDTExtAddr CAN extended address for a USDT response.
Usage: response handling.
CP_CanRespUUDTFormat CAN Id format for a UUDT response.
Used for response handling.
CP_CanRespUUDTExtAddr CAN Id extended address for a UUDT response.
Usage: response handling.
CP_CanRespUUDTId CAN Id for a UUDT response.
Usage: response handling. Set the value to 0xFFFFFFFF, if the
ComParameter shall not be used.
Table 59: Communication Parameters
8. After completing these settings and PDUConnect has been called successfuly, sending
and receiving of diagnostic services is possible.
When PDUConnect is called, the ComLogicalLink physically connects to the vehicle interface.
The communication state of the ComLogicalLink must be "offline" when the function is called.
After execution, the state changes to "online". The calling of this function is required before
any communication to the vehicle ECU can take place.
9. Now ComPrimitives can be created and sent. The ComPrimitive’s behaviour can be
configured using the ComPrimitive’s PDU data and control parameters in the “Edit PDU” frame
of the LogicalLink dialog:
a. PDU data are directly defined at the “Edit PDU”combobox. Previously defined
data combination can be recalled using the combobox list values.
b. TX Count defines the number of send operations (=”NumSendCycles”)
c. RX Count defines the number of receive operations (=”NumReceiveCycles”)
d. Cycle Time defines the time interval for cyclic operations (=”CycleTime”)
108

e. TempParamUpdate allows to use an updated set of ComParameter just for
the next ComPrimitive. The ComParameters are defined using the
“EditLoliParams” dialog.
f. Edit Tx Flags allows to specify the ComParameter’s TX flag settings
Figure 14: D-PDU API test application-Transmit Flags
g. The ComParameters are created using the buttons in the “ComPrimitives”
frame. For each ComParameter type a specific button exists:
STARTCOMM
The STARTCOMM ComPrimitive initializes the diagnostic communication with the ECU and
starts tester present messages according to the ComParameter settings.
SEND/RECEIVE
SEND/RECEIVE ComPrimitives are used for generic communication operations. In
combination with the ComPrimitive control parameters described above, the following
communication patterns can be initiated:
- SEND ONLY (NumReceiveCycles = 0)
The ComPrimitive is considered to be a send only ComPrimitive if the number of receive
cycles is equal to zero and the number of send cycles is not equal to zero.
- RECEIVE ONLY (NumSendCycles = 0)
The ComPrimitive is considered to be a receive only ComPrimitive if the number of send
cycles is equal to zero and the number of receive cycles is not equal to zero. In this case, the
value NumReceiveCycle is used to identify messages that match the
ExpectedResponseStructure by monitoring the vehicle bus.
- SEND and RECEIVE (NumReceiveCycles!= 0 NumSendCycles!= 0)
In this case, each time the ComPrimitive is sent, it will try to deliver the number of responses
specified in NumReceiveCycles. If this receive cycles number is not reached before a receive
timeout occurs, an error event is generated by the ComPrimitive. The error event indicates that
a receive timeout occurred. A cyclic transmission continues even after a receive timeout
occured. The periodic ComPrimitive will not transition to PDU_COPST_FINISHED by itself.
109

- IS-MULTIPLE Multiple Expected Responses (NumReceiveCycles = -2),
The receive timer is reset every time a received message matches the
ExpectedResponseStructure. If there is no matching in the given time span an error event is
generated. No error is generated if at least one matching response was received until the
receive timeout occurs.
- IS-CYCLIC Infinite Responses (NumReceiveCycles = -1),
The ComPrimitive is placed into a receive only mode after the ComLogicalLink finishes the
transmission and receives the first positive response. In this mode responses are still received
from the cyclic ComPrimitive while other ComPrimitives can be transmitted. The ComPrimitive
status changes to PDU_COPST_FINISHED if there is a cyclic receive timeout. If no receive
timeout occurs, the application must use PDUCancelComPrimitive in order to stop and finish
the ComPrimitive.
The ComPrimitive transitions to PDU_COPST_FINISHED and the status item is placed on the
ComLogicalLink’s Event Queue once all the expected responses are received and all
transmission send cycles are completed.
DELAY
The Delay ComPrimitive, causes a delay according to the given time span, before the next
ComPrimitive is executed.
UPDATEPARAM
The ComParameters related to a ComLogicalLink are copied from the working buffer to the
active buffer. Before the update PDUSetComParam is called, so that the values are passed to
the D-PDU API, which modifies the values in the working buffer.
The working buffer holds the temporary ComParameter values. To modify the values in the
working buffer the API function PDUSetComParam is used. The API function
PDUGetComParam returns these values.
The values from the working buffer are not currently used for communication. These values
are copied in the active buffer using the UPDATEPARAM ComPrimitive. The active buffer
holds the values that are currently used for communication. All ComParameter editing is
performed in the working buffer. UPDATEPARAM has the purpouse to apply these
modifications. For further details please see the ISO specification ISO 22900-2.
RESTOREPARAM
The ComParameters related to a ComLogicalLink are copied from the active buffer to the
working buffer. To obtain the values from the active buffer the RESTOREPARAM
ComPrimitive and thereafter PDUGetComParam API function can be used.
Cancel Primitive
The ComPrimitive selected by the combobox list entry will be cancelled after pressing the
“CancelPrimitive” button.
110

111
STOPCOMM
The diagnostic communication with the ECU will be stopped by sending the
PDU_COPT_STOPCOMM ComPrimitive. The behaviour depends on the protocol. The
ComLogicalLink’s status changes to PDU_CLLST_ONLIINE state and no further tester
present messages will be sent.
10.PDUDisconnect
Physically disconnects the ComLogicalLink from the communication line. Communication
resources and internal memory segments are freed. Also system-level drivers are
disconnected.
11. Exit
After disconnecting (“PDUDisconnect” Button) the ComLogicalLink, it can be destroyed by
pressing the “Exit” button (PDUDestroyComLogicalLink [ISO 22900-2 – 9.4.10] will be
executed). The ComLogicalLink dialog will be closed afterwards.

10 D-PDU API Configuration Manager
The D-PDU API Configuration Manager, delivered with the Softing D-PDU API software
enables the user to execute the basic settings in a confortable manner.
These settings include:
• Configuration of EDIC interface modules connected to the D-PDU API Software
• Testing the EDIC interface for correct installation
112

113
• Tracing of D-PDU API Function calls on different information levels
• Logging of communication data on the bus between testequipment
and vehicle

11 D-PDU API Demonstrator
The demonstrator code which is available after the D-PDU API installation provides a
sequence of steps that can be followed in a communication process from the initial connection
to the D-PDU API Library, passing through the setting up a ComLogicalLink, starting vehicle
communications and finishing with the disconnection from the D-PDU API library.
114

12 Appendix
12.1 Error codes
All error codes of the Softing D-PDU API implementation are listed in the MDF file. In addition
the error codes are listed in the corresponding protocol documentation.
115

12.2 Troubleshooting
Below additional troubleshooting help is provided for possible cases, which might occur in a
Softing D-PDU API software installation.
Trouble case License not found
System
behaviour
Error code PDU_ERR_FUNCTION_FAILED plus the special value
PDU_CLLHDL_LICENSE_CHECK_FAILED as ComLogicalLink handle is
reported upon function call PDUCreateComLogicalLink.
Measure For both license mechanisms a license file is used to carry the license
information. The license file is distributed on the distribution CD and installed
by the setup program.
To use the D-PDU API software the interface and the associated license file
are required. In case of licensing via USB hardlock dongle the associated
dongle has to be connected to the PC.
Notes The license check is executed during the API function call
PDUCreateComLogicalLink. In case of a missing license the function will
report an error code PDU_ERR_FUNCTION_FAILED plus special value
PDU_CLLHDL_LICENSE_CHECK_FAILED as ComLogicalLink handle. The
special value is defined in file pdu_api.h as follows:
#define PDU_CLLHDL_LICENSE_CHECK_FAILED 0x80000000
Trouble case ComParameter not supported
System
behaviour
When PDUSetComParamis called, it returns with error code
PDU_ERR_COMPARAM_NOT_SUPPORTED, because the D-PDU API
implementation doesn’t support the specified ComParameter.
Measure Ignore the error and continue in your application setting the other
ComParameters. Please be aware, that the specific functionality of the
unsupported ComParameter will be missing. However - since only a few
ComParameters are not supported at the moment - many applications can be
used without implications.
Notes Please see the respective protocol documentation for a list of supported
ComParameters.
Trouble case Internal error code reported as extra error code
System
ehaviour
A function call returns with additional (extra) error code described as internal
error in chapter 12.1.
Measure Please check your application code and your ComParameters. If the problem
still occurs, please contact Softing.
Notes
Table 60: Troubleshooting
116

12.3 Trace mechanism
Softing’s D-PDU API software implementation includes a trace mechanism on API level. When
using the D-PDU API, different levels of trace information can be activated to support the user
in case of errors as well as to provide full tracing information on the Softing D-PDU API
software stack.
Use the Softing D-PDU API Configuration Manager to activate the API trace mechanism. It
can be started from the Windows Start Menu: Start Alle Programme Softing D-PDU API
for VCIs <version number> Softing D-PDU API Configuration Manager.
The resulting trace information is written to the file "Softing_PDU_API_Trace.txt. When the
selected size for the trace file is reached, the file is renamed to
Softing_PDU_API_TraceOld.txt and an existing *Old.txt file is overwritten.
12.4 Support and maintenance
The D-PDU API software implementation from Softing includes free installation support.
Maintenance work is done in context with product release cycles. Further maintenance or
application support is optional and can be offered on request.
To send support requests please use the support form our website www.softing.com.
117

118
12.5 Additional services
Softing customers are supported in a target-oriented manner in their projects. Engineering
services for custom specific integration and design as well as consulting services are offered
on request. Particularly with new projects in connection with D-PDU API, D-Server and ODX –
particularly with problems on migration of old systems – Softing can implement its existing
expertise to great effect.
12.6 RDF file
The RDF (root description file) is a xml file which holds information regarding every D-PDU
API installed on the system. The xml tags for this file are defined in the D-PDU API
specification [ISO 22900-2 – F.1].
The “SHORT_NAME” tag represent a simbolic name for the installed D-PDU API.
The three URI elements (LIBRARY_FILE URI, MODULE_DESCRIPTION_FILE URI,
CABLE_DESCRIPTION_FILE URI) contain the full path to the D-PDU API dll, the MDF.xml
(Module Description File) file and the CDF.xml (Cable Description File) file.
The remaining tags are not necessary.
-<MVCI_PDU_API_ROOT
- <MVCI_PDU_API>
<SHORT_NAME>EDIC_D_PDU_API_x.yy.zz </SHORT_NAME>
<DESCRIPTION>EDIC D-PDU API Implementation</DESCRIPTION>
<SUPPLIER_NAME>Softing AG</SUPPLIER_NAME>
<LIBRARY_FILE URI="file:/C:/Programme/PDU-API/x.yy.zz
/vecom/PDUAPI_SoftingAG_x.yy.zz.dll" />
<MODULE_DESCRIPTION_FILE URI="file:/C:/Programme/PDU-API/x.yy.zz
/vecom/MDF_SoftingAG_EDIC-PDU-API_x.yy.zz.xml" />
<CABLE_DESCRIPTION_FILE URI="file:/C:/Programme/PDU-API/x.yy.zz
/vecom/CDF_SoftingAG_EDIC-PDU-API_x.yy.zz.xml" />
</MVCI_PDU_API>
</MVCI_PDU_API_ROOT>

13 References and Index
13.1 References
/1/ ISO 22900-1 (DIS) Road vehicles -- Modular vehicle
communication interface (MVCI) - Part 1: Hardware
design requirements
communication interface (MVCI) - Part 2: D-PDU API
(Diagnostic Protocol Data Unit Application
Programmer Interface)
communication interface (MVCI) - Part 3: Server API
(Application Programmer Interface)
/4/ ISO 22901-1 (DIS) Road vehicles - Open diagnostic
data exchange (ODX) - Part 1: Data model
specification
/5/ ISO 11898: Road vehicles - Interchange of digital
information; Controller area network (CAN) for high-
speed communication
Notes:
The ISO specifications can be purchased at www.iso.org.
119

13.2 Index of figures
Figure 1: MVCI system structure 2
Figure 2: Data exchange in MVCI systems 3
Figure 3: D-PDU API products and solutions from Softing 4
Figure 4: D-PDU API system with single VCI module 13
Figure 5: D-PDU API system with multiple VCI modules from one tool supplier 14
Figure 6: D-PDU API system multiple VCI modules from different tool suppliers 14
Figure 7: D-PDU API system with 3 ComLogicalLinks on 1 resource 16
Figure 8: D-PDU API migration system example 21
Figure 9: D-PDU API test application 103
Figure 10: D-PDU API test application-Open Logical Link 105
Figure 11: D-PDU API test application-Edit ComParameters 106
Figure 12: D-PDU API test application- Edit URID Table 106
Figure 13: D-PDU API test application-URID Table 107
Figure 14: D-PDU API test application-Transmit Flags 109
120

13.3 Index of tables
Table 1: Software distribution documents 6
Table 2: Licensing model 8
Table 3: Standardized communication protocols 17
Table 4: Communication parameter table (example) 18
Table 5: Communication parameters (example) 19
Table 6: D-PDU API functions 23
Table 7: ComPrimitives 27
Table 8: PDUConstruct return values 29
Table 9: PDUDestruct return values 30
Table 10: PDUModuleConnect return values 33
Table 11: PDUModuleDisconnect return values 33
Table 12: PDURegisterEventCallback return values 34
Table 13: PDUIoCtl return values 37
Table 14: PDUGetVersion return values 38
Table 15: PDUGetStatus return values 40
Table 16: PDUGetLastError return values 42
Table 17: PDUGetObjectId return values 43
Table 18: PDUGetResourceId return values 45
Table 19: PDUGetResourceStatus return values 46
Table 20: PDUGetConflictingResources return values 48
Table 21: PDUGetModelIds return values 50
Table 22: PDULockResource return values 52
Table 23: PDUUnlockResource return values 53
Table 24: PDUCreateComLogicalLink return values 56
Table 25: PDUDestroyComLogicalLink return values 58
Table 26: PDUConnect return values 60
Table 27: PDUDisconnect return values 62
Table 28: PDUGetTimestamp return values 63
Table 29: PDUGetComParam return values 64
Table 30: PDUSetComParam return values 67
Table 31: PDUGetUniqueRespIdTable return values 69
Table 32: PDUSetUniqueRespIdTable return values 71
Table 33: PDUStartComPrimitive return values 76
Table 34: PDUCancelComPrimitive return values 77
Table 35: PDUGetEventItem return values 79
Table 36: PDUDestroyItem return values 80
121

122
Table 37: D-PDU API IOCTL commands 81
Table 38: PDU_IOCTL_RESET return values 82
Table 39: PDU_IOCTL_CLEAR_TX_QUEUE return values 83
Table 40: PDU_IOCTL_SUSPEND_TX_QUEUE return values 84
Table 41: PDU_IOCTL_RESUME_TX_QUEUE return values 85
Table 42: PDU_IOCTL_CLEAR_RX_QUEUE return values 86
Table 43: PDU_IOCTL_READ_VBATT return values 87
Table 44: PDU_IOCTL_SET_PROG_VOLTAGE return values 88
Table 45: PDU_IOCTL_READ_PROG_VOLTAGE return values 89
Table 46: PDU_IOCTL_GENERIC return values 90
Table 47: PDU_IOCTL_SET_BUFFER_SIZE return values 91
Table 48: PDU_IOCTL_START_MSG_FILTER return values 92
Table 49: PDU_IOCTL_STOP_MSG_FILTER return values 93
Table 50: PDU_IOCTL_CLEAR_MSG_FILTER return values 94
Table 51: PDU_IOCTL_SET_EVENT_QUEUE_PROPERTIES return values 95
Table 52: PDU_IOCTL_GET_CABLE_ID return values 96
Table 53: PDU_IOCTL_SEND_BREAK return values 97
Table 54: PDU_IOCTL_READ_IGNITION_SENSE_STATE return values 98
Table 55: D-PDU API implementation limitations 99
Table 56: D-PDU API implementation restrictions 100
Table 57: Protocol support 101
Table 58: Demo application files 102
Table 59: Communication Parameters 108
Table 60: Troubleshooting 116

D pduapi user-manual

More Related Content

What's hot (20)

Similar to D pduapi user-manual (20)

Recently uploaded (20)

D pduapi user-manual