> For the complete documentation index, see [llms.txt](https://sandbox-docs.verifone.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sandbox-docs.verifone.com/s-adk-5.1-programmers-guide/readme/system_overview/pg_all_components/pg_cpl_users_guide.md).
# ADK-CPL Programmers Guide
## Preface
This document is for programmers and developers who want to understand and use the ADK-CPL extension.
### Audience
This guide provides information on the usage of the ADK-CPL system.
### Organization
[Chapter 1, Introduction:](#cpl_introduction) Provides a general introduction to ADK-CPL
[Chapter 2, Getting Started:](#cpl_getting_started) Presents an introduction in ADK-CPL usage.
[Chapter 3, Programming:](#cpl_programming) Supplies ADK-CPL programming information.
[Chapter 4, System Setup and Requirements:](#cpl_setup) Presents environment setup and dependencies.
[Chapter 5, Troubleshooting:](#cpl_troubleshooting) Gives solutions for possible issues in ADK-CPL.
### Prerequisites
## Introduction
ADK-CPL allows to use the functionality of the Commerce Platform in V/OS and V/OS2 as a static library.
Each library of libcpl only works with a special trigger schema. Currently changes inside the trigger schema can lead to broken backward compatibility. The only solution to fix it is to link the needed library static against the payment application.
The communication flow is shown below
### Triggers
#### Payment flow triggers
* CP\_SYSTEM\_NOTIFIES\_TRANSACTION\_STARTED
* CP\_SYSTEM\_REQUESTS\_BASKET\_ADJUSTMENT
* CP\_SYSTEM\_NOTIFIES\_BASKET\_FINALIZED
* CP\_SYSTEM\_REQUESTS\_LOYALTY
* CP\_SYSTEM\_REQUESTS\_AMOUNT\_ADJUSTMENT
* CP\_SYSTEM\_NOTIFIES\_AMOUNT\_FINALIZED
* CP\_SYSTEM\_REQUESTS\_ALT\_PAYMENT
* CP\_SYSTEM\_NOTIFIES\_CARD\_PRESENTED
* CP\_SYSTEM\_NOTIFIES\_CARD\_BIN\_RECEIVED
* CP\_SYSTEM\_REQUESTS\_PAYMENT\_AMOUNT\_ADJUSTMENT
* CP\_SYSTEM\_NOTIFIES\_AUTHORIZATION\_COMPLETED
* CP\_SYSTEM\_NOTIFIES\_PAYMENT\_COMPLETED
* CP\_SYSTEM\_REQUESTS\_RECEIPT\_MANAGEMENT
* CP\_SYSTEM\_NOTIFIES\_TRANSACTION\_ENDED
#### Non payment triggers
* CP\_SYSTEM\_NOTIFIES\_IDLE\_ENTERED
* CP\_SYSTEM\_NOTIFIES\_MANUAL\_LAUNCH\_SELECTED
#### API Trigger
* CP\_APP\_REQUESTS\_ENCRYPTED\_CARD
* CP\_APP\_REQUESTS\_PRINT
* CP\_APP\_REQUESTS\_APPEND\_RECEIPT
* CP\_APP\_REQUESTS\_PAYMENT\_TRANSACTION\_START
* CP\_APP\_REQUESTS\_CARD\_DATA
* CP\_APP\_REQUESTS\_SEND\_DATA\_TO\_POS
* CP\_APP\_REQUESTS\_RECEIPT
### Concepts
#### Uniform Interface
## Getting Started
The CPL library comes with the sample application cpltest that demonstrates system features and provides a starting point for application developers who use the CPL library. It can be found in the *test* folder (test).
The CPL library is provided on different target platforms. The following sections describe how to use the sample application cpltest on these platforms. In addition, this chapter gives general information about required components to run ADK-CPL (runtime libraries).
### Running ADK-CPL on V/OS
To run the ADK-CPL on V/OS and V/OS2. If the sample application cpltest shall be used too, the ADK-GUI packet needs to be installed with all its requirements.
### Running on Verix
To run the ADK-CPL on Verix. If the sample application cpltest shall be used too, the ADK-GUI packet needs to be installed with all its requirements.
Furthermore, ADK-CPL depends on some libraries coming along with OS and the EOS. Please always use the newest OS and EOS versions available on Verifone DevNet.
### Running on Linux
## Programming
### ADK-CPL Deployment Options
The ADK-CPL system provides different header files ([Commerce.h](/s-adk-5.1-programmers-guide/readme/files/dir_2002fcb36e937be08e088f9ab4e81de8/dir_fad52422ca9a0153aca9cfe879bff259/dir_613e11e510006a27889deef70cf7d9b4/_commerce_8h.md), [Api.h](/s-adk-5.1-programmers-guide/readme/files/dir_2002fcb36e937be08e088f9ab4e81de8/dir_fad52422ca9a0153aca9cfe879bff259/dir_613e11e510006a27889deef70cf7d9b4/_api_8h.md), [CpTrigger.h](/s-adk-5.1-programmers-guide/readme/files/dir_2002fcb36e937be08e088f9ab4e81de8/dir_fad52422ca9a0153aca9cfe879bff259/dir_613e11e510006a27889deef70cf7d9b4/_cp_trigger_8h.md), [EnvironmentDataProvider.h](/s-adk-5.1-programmers-guide/readme/files/dir_2002fcb36e937be08e088f9ab4e81de8/dir_fad52422ca9a0153aca9cfe879bff259/dir_613e11e510006a27889deef70cf7d9b4/_environment_data_provider_8h.md) ITransactionDataProvider) that exports the CPL library API function calls. Because of compatibility problems between the different schema versions, the library only supports static linking.
#### Headers and binary deliveries
The ADK-CPL system is composed of the following deliveries:
| File | Purpose |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| [**Api.h**](/s-adk-5.1-programmers-guide/readme/files/dir_2002fcb36e937be08e088f9ab4e81de8/dir_fad52422ca9a0153aca9cfe879bff259/dir_613e11e510006a27889deef70cf7d9b4/_api_8h.md) | CPL function header file with exported definitions/functions. |
| [**Commerce.h**](/s-adk-5.1-programmers-guide/readme/files/dir_2002fcb36e937be08e088f9ab4e81de8/dir_fad52422ca9a0153aca9cfe879bff259/dir_613e11e510006a27889deef70cf7d9b4/_commerce_8h.md) | CPL function header file with exported definitions/functions. |
| [**EnvironmentDataProvider.h**](/s-adk-5.1-programmers-guide/readme/files/dir_2002fcb36e937be08e088f9ab4e81de8/dir_fad52422ca9a0153aca9cfe879bff259/dir_613e11e510006a27889deef70cf7d9b4/_environment_data_provider_8h.md) | CPL function header file with exported definitions/functions. |
[**ITransactionDataProvider.h**](/s-adk-5.1-programmers-guide/readme/files/dir_2002fcb36e937be08e088f9ab4e81de8/dir_fad52422ca9a0153aca9cfe879bff259/dir_613e11e510006a27889deef70cf7d9b4/_i_transaction_data_provider_8h.md) | CPL function header file with exported definitions/functions.
**libcpl.a** | CPL system client library **cpltest** | CPL sample application binary for V/OS, V/OS2, Verix and linux
All header files can be found in the 'include/commerce' directory.
An application has to be linked with libcpl.
#### Multi-Application-Controller Resource Subfolder Support
Multi-Application-Controller (MAC) is used to run several applications in parallel on a terminal. Since version 2.5.0 the UI system has added support to lookup resources in a separate subdirectory for each application to avoid resource location conflicts. For this, MAC sets up the environment variable `GUIPRT_APPNAME`, which provides a name for each application that is used for the subfolder `appname:`
```cpp
www//
```
or
```cpp
www//x
```
`GUIPRT_APPNAME` is automatically considered during startup of an application so that most of the MAC handling is transparent to the application. Please note that the variable is just used to set up the default values for `UI_PROP_RESOURCE_PATH` and `UI_PROP_RESOURCE_DEFAULT_PATH`. Once an application has set the properties during runtime, value of `GUIPRT_APPNAME` is ignored.
An application can also set GUIPRT\_APPNAME by itself to move the default resource folder. For this the environment variable has to be set using `setenv()` before calling any ADKGUI function.
## System Setup and Requirements
The following are the hardware and software requirements of the ADK-CPL system.
## Hardware Support
The ADK-CPL system is hardware platform agnostic and supports installation on V/OS, Raptor, and Verix terminals.
The ADK-CPL system is intended to run across the entire hardware portfolio. The following table list different characteristics of these devices.
| Model | Touch | Color | Resolution | Keypad | Function Keys | Resource Path |
| --------------- | ----- | ----- | ---------- | -------------------- | ----------------- | ------------- |
| Vx520 (B/W) | No | No | 128x64 | 0-9,\*,#,CAN,CORR,OK | 4+4+Alpha | 128x64M24N |
| Vx6, Vx8 | Yes | Yes | 240x320 | 0-9,\*,#,CAN,CORR,OK | --- | 240x320C15T |
| Vx675/Vx5 color | No | Yes | 320x240 | 0-9,\*,#,CAN,CORR,OK | 4+4\*Cursor+Enter | 320x240C24N |
| Mx915 | Yes | Yes | 480x272 | 0-9,CAN,CORR,OK | --- | 480x272C13T |
| Mx925 | Yes | Yes | 800x480 | 0-9,CAN,CORR,OK | --- | 800x480C13T |
| Ux100 | No | No | 128x64 | 0-9,CAN,CORR,OK,INFO | 2 | 128x64M16N |
| e265 | No | No | 160x120 | 0-9,\*,#,CAN,CORR,OK | --- | 160x120M15N |
| e285 | Yes | Yes | 240x320 | 0-9,\*,#,CAN,CORR,OK | --- | 240x320C15T |
| e315/335 | No | No | 128x32 | 0-9,\*,#,CAN,CORR,OK | --- | 128x32M15N |
| e355 | No | Yes | 320x240 | 0-9,\*,#,CAN,CORR,OK | --- | 320x240C15N |
| Carbon X10 | Yes | Yes | 854x480 | --- | --- | 854x480C0T |
| M400 | Yes | Yes | 854x480 | 0-9,\*,#,CAN,CORR,OK | --- | 854x480C15T |
| P400/V400 | Yes | Yes | 320x480 | 0-9,\*,#,CAN,CORR,OK | --- | 320x480C15T |
| P200/V200c | No | Yes | 240x320 | 0-9,\*,#,CAN,CORR,OK | 2+4\*Cursor | 240x320C21N |
| V200t/V205c | No | Yes | 320x240 | 0-9,\*,#,CAN,CORR,OK | 2+4\*Cursor | 320x240C21N |
| V240m/V400m | Yes | Yes | 320x480 | 0-9,\*,#,CAN,CORR,OK | --- | 320x480C15T |
| C680 | Yes | Yes | 320x480 | 0-9,\*,#,CAN,CORR,OK | --- | 320x480C15T |
Users need to take these characteristics into account when designing GUI dialogs with CPL library support for the different hardware platforms.
{% hint style="info" %}
C680 has an additional power button, it is not counted as keypad key since it cannot be used for input.
{% endhint %}
{% hint style="info" %}
For a detailed description of the API functions, see .
{% endhint %}
## Software Requirements
ADK-CPL requires the installation of corresponding platform packages. For details please refer to the release notes.
## Troubleshooting
## Support for ADKLOG
ADK-CPL has added support for ADKLOG component. ADKLOG is required to implement the new ADK logging concept, which provides the Logging Control Panel (LCP) used as central instance to configure and enable logging for the several ADK components. For this, LCP uses configuration files (for CPL), which are read by `liblog` library. If installed on the system, `liblog` library will be used by client import libraries (`libvfiguiprt`, `libvfiprt`) and server components (`guiprtserver`, `guiserver`, `prtserver`) to output logging messages. In this case, the logging messages are passed to `liblog` library instead of using console logging mechanism (with EOSLog or stderr), which is described above.
In order to lookup the corresponding configuration files, ADKLOG uses component identifiers, which are reserved for each ADK component. Components participating in Commerce Platfrom operation are following:
| Component Id | Configuration file | Description |
| ------------ | ------------------ | --------------------------------------------- |
| `CPL` | `CPL_log.conf` | Commerce Platform library |
| `PRX` | `PRX_log.conf` | Cloudproxy daemon |
| `MAC` | `MAC_log.conf` | Multi Application Controller daemon |
| `MACCL` | `MACCL_log.conf` | Multi Application Controller Commerce library |
| `CPR` | `CPR_log.conf` | Commerce Platform Runtime library |
The configuration files contain several settings for logging like output channels, verbosity and a logging mask. For more details about configuration settings or logging message formats, please refer to documentation of ADKLOG project.
## Cloud connectivity
First step that needs to be done to solve problem appeared with Commerce Platform is to check whether cloud is available. All network traffic produced by CP applications is verified and directed by Cloudproxy daemon. It is possible to check whether Cloudproxy is installed and operating by running CP Downloader application from the desktop. If the daemon is running then Cloudproxy entry should be present in CP downloader main menu. There is Connectivity Check sub entry in the Cloudproxy menu.
| | | |
| -------------------------------- | -------------------------------- | -------------------------------- |
|  |  |  |
Pressing it makes a test request to the cloud and displays the response after few seconds. When a red line with text "Cloud not reachable" appears, then cloud support team should be contacted to determine and solve the problem. In success case a green line with text "Cloud reachable" will be seen. Examples of different response codes are shown below.
| | | |
| -------------------------------- | -------------------------------- | -------------------------------- |
|  |  |  |
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://sandbox-docs.verifone.com/s-adk-5.1-programmers-guide/readme/system_overview/pg_all_components/pg_cpl_users_guide.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.