> 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_msr_programmers_guide.md).

# ADK-MSR Programmers Guide

## Preface <a href="#sec_msr_preface" id="sec_msr_preface"></a>

This document is for programmers and developers who want to understand and use the ADK-MSR.

### Audience <a href="#subsec_msr_audience" id="subsec_msr_audience"></a>

This guide provides all the information required for application developers to integrate and utilize the functionality of the ADK-MSR.

### Organization <a href="#subsec_msr_organization" id="subsec_msr_organization"></a>

This guide is organized as follows:

[Introduction](#sec_msr_introduction): Provides a summary of ADK-MSR.

[Getting Started](#sec_msr_getting_started): Presents an introduction in ADK-MSR usage.

[Programming](#sec_msr_programming): Supplies ADK-MSR programming information.

[System Setup and Requirements](#sec_msr_system_setup_and_requirements): Supplies information about required dependencies.

[Troubleshooting](#sec_msr_troubleshooting): Gives solutions for possible issues in ADK-MSR.

[Appendix](#sec_msr_appendix): Links to related documents.

## Introduction <a href="#sec_msr_introduction" id="sec_msr_introduction"></a>

ADK-MSR provides access to the terminals magnetic card reader.

Supported card types (depends also on OS support):

* **ISO/IEC 7811** activation by [MSR\_DETECT\_ISO](/s-adk-5.1-programmers-guide/readme/modules/group___m_s_r___o_p_t_i_o_n_s___b_i_t_m_a_s_k.md#ga552908ea327761a80fc0557a4f617f97), result given with [MSR\_CARD\_ISO](/s-adk-5.1-programmers-guide/readme/modules/group___m_s_r___t_r_a_c_k___t_y_p_e_s.md#gacd72026476677415eaf482b2fb2e0032)
* **JIS II** activation by [MSR\_DETECT\_JIS\_II](/s-adk-5.1-programmers-guide/readme/modules/group___m_s_r___o_p_t_i_o_n_s___b_i_t_m_a_s_k.md#ga9f84cf93e845a72a46da5530a2f0fda6), result given with [MSR\_CARD\_JIS\_II](/s-adk-5.1-programmers-guide/readme/modules/group___m_s_r___t_r_a_c_k___t_y_p_e_s.md#gaf1dad30c2494f4da59022687eb8e9dc1)
* **US Driving License (CADL, AAVMA)** activation by [MSR\_ENABLE\_LICENSE\_DECODE](/s-adk-5.1-programmers-guide/readme/modules/group___m_s_r___o_p_t_i_o_n_s___b_i_t_m_a_s_k.md#ga57908026ec7d34ab1eab699f5a01bfdc) Supported on V/OS, but on Engage (VOS2) only for M440

### Components <a href="#subsec_msr_intro_compos" id="subsec_msr_intro_compos"></a>

To make use of the magnetic card reader, you need the following components of ADK-MSR:

* [msr.h](/s-adk-5.1-programmers-guide/readme/files/dir_b259c67979486db4cd1816234700c14a/dir_699851f087f6e6136e28f04fc8a16e7d/msr_8h.md)
* [msr\_common.h](/s-adk-5.1-programmers-guide/readme/files/dir_b259c67979486db4cd1816234700c14a/dir_699851f087f6e6136e28f04fc8a16e7d/msr__common_8h.md)
* `libmsr.so`

This is illustrated in the following image:

### Android <a href="#sec_msr_intro_android" id="sec_msr_intro_android"></a>

In Android the ADK-MSR is hidden inside SDI. So application has to use the "Card Detection (23-01)" resp. "MSR Read (21-01)" from [ADK-SDI Programmers Guide](/s-adk-5.1-programmers-guide/readme/system_overview/pg_all_components/pg_sdi_users_guide.md).

### VOS3 <a href="#sec_msr_intro_vos3" id="sec_msr_intro_vos3"></a>

In VOS3 ADK-MSR is accessible through SDI. The ADK-MSR-interface is rebuild in [ADK-SDI-Client Programmers Guide](/s-adk-5.1-programmers-guide/readme/system_overview/pg_all_components/pg_sdiclient_users_guide.md).

### Two-Piece Solution <a href="#sec_msr_intro_2piece" id="sec_msr_intro_2piece"></a>

Former Two-Piece Solution with Client/Server architecture for MSR, TEC, ... is not supported anymore. SDI EPP has to be used instead (see [ADK-SDI Programmers Guide](/s-adk-5.1-programmers-guide/readme/system_overview/pg_all_components/pg_sdi_users_guide.md)).

## Getting Started <a href="#sec_msr_getting_started" id="sec_msr_getting_started"></a>

### Sample Application <a href="#sec_msr_sample" id="sec_msr_sample"></a>

Link your application with `libmsr.so`.

#### Wait until card swipe (blocking/polling API) <a href="#sec_msr_sample_blocking" id="sec_msr_sample_blocking"></a>

```cpp
#include "msr.h"
....
if (MSR_Activate(NULL, NULL) == MSR_OK)
{
  MSR_TrackData tracks;
  MSR_DecodedData data;
  // Wait 10 seconds for a card swipe:
  if (MSR_GetData(10000, &tracks, &data) == MSR_OK)
  {
   // card read successfully
  }
  (void) MSR_Deactivate();
}
....
```

The function [MSR\_GetData()](/s-adk-5.1-programmers-guide/readme/files/dir_b259c67979486db4cd1816234700c14a/dir_699851f087f6e6136e28f04fc8a16e7d/msr_8h.md#ad00fdde838f486d43be689650ab58d43) blocks until the timeout has elapsed or a card has been swiped. You could also implement a periodic polling (with reduced timeout). So it's possible to e.g. check if the cancel key was pressed. Another option is to poll the [MSR\_DataAvailable()](/s-adk-5.1-programmers-guide/readme/files/dir_b259c67979486db4cd1816234700c14a/dir_699851f087f6e6136e28f04fc8a16e7d/msr_8h.md#a8096fa193f035eb4b80673260d720477) and (if returned true) call [MSR\_GetData()](/s-adk-5.1-programmers-guide/readme/files/dir_b259c67979486db4cd1816234700c14a/dir_699851f087f6e6136e28f04fc8a16e7d/msr_8h.md#ad00fdde838f486d43be689650ab58d43) only once with timeout 0.

#### Register callback for swipe event <a href="#sec_msr_sample_callback" id="sec_msr_sample_callback"></a>

```cpp
#include "msr.h"
....
void callback(void *data)
{
  // card swiped -> read data
  MSR_TrackData tracks;
  MSR_DecodedData data;
  if (MSR_GetData(0, &tracks, &data) == MSR_OK)
  {
   // card read successfully
  }
}
if (MSR_Activate(&callback, NULL) == MSR_OK)
{
  // Do something here until callback has been called....
  while (...)
  {
  }
  (void) MSR_Deactivate();
}
....
```

[MSR\_GetData()](/s-adk-5.1-programmers-guide/readme/files/dir_b259c67979486db4cd1816234700c14a/dir_699851f087f6e6136e28f04fc8a16e7d/msr_8h.md#ad00fdde838f486d43be689650ab58d43) can be either called within the callback function or (after the callback has been invoked) in another function/thread. But keep in mind that you can obtain any card swipe's data only once.

## Programming <a href="#sec_msr_programming" id="sec_msr_programming"></a>

### Programming and API Principles <a href="#subsec_msr_programming_and_api_principles" id="subsec_msr_programming_and_api_principles"></a>

The API consists of the following functions:

* [MSR\_Version()](/s-adk-5.1-programmers-guide/readme/files/dir_b259c67979486db4cd1816234700c14a/dir_699851f087f6e6136e28f04fc8a16e7d/msr__common_8h.md#a4c82e0afa0ae93bb7a97a03431c202b8)
* [MSR\_SetTraceCallback()](/s-adk-5.1-programmers-guide/readme/files/dir_b259c67979486db4cd1816234700c14a/dir_699851f087f6e6136e28f04fc8a16e7d/msr__common_8h.md#ac4fab89b234ae87c7da91fb529b833e0)
* [MSR\_SetOptions()](/s-adk-5.1-programmers-guide/readme/files/dir_b259c67979486db4cd1816234700c14a/dir_699851f087f6e6136e28f04fc8a16e7d/msr_8h.md#ac3c6f568aa57690a8b369936fc362c2a)
* [MSR\_Activate()](/s-adk-5.1-programmers-guide/readme/files/dir_b259c67979486db4cd1816234700c14a/dir_699851f087f6e6136e28f04fc8a16e7d/msr_8h.md#a1e92fd29720fecbf50da24a30c7b512f)
* [MSR\_Deactivate()](/s-adk-5.1-programmers-guide/readme/files/dir_b259c67979486db4cd1816234700c14a/dir_699851f087f6e6136e28f04fc8a16e7d/msr_8h.md#aac28b2c3771f8221fc26a35f0fd6d0f8)
* [MSR\_DataAvailable()](/s-adk-5.1-programmers-guide/readme/files/dir_b259c67979486db4cd1816234700c14a/dir_699851f087f6e6136e28f04fc8a16e7d/msr_8h.md#a8096fa193f035eb4b80673260d720477)
* [MSR\_GetData()](/s-adk-5.1-programmers-guide/readme/files/dir_b259c67979486db4cd1816234700c14a/dir_699851f087f6e6136e28f04fc8a16e7d/msr_8h.md#ad00fdde838f486d43be689650ab58d43)
* [MSR\_GetData2()](/s-adk-5.1-programmers-guide/readme/files/dir_b259c67979486db4cd1816234700c14a/dir_699851f087f6e6136e28f04fc8a16e7d/msr_8h.md#a1bf2f70013c79b94a09b3504607a0667)
* [MSR\_GetData3()](/s-adk-5.1-programmers-guide/readme/files/dir_b259c67979486db4cd1816234700c14a/dir_699851f087f6e6136e28f04fc8a16e7d/msr_8h.md#ab2415e817a7d2a1189897757485ff660)
* [MSR\_GetData4()](/s-adk-5.1-programmers-guide/readme/files/dir_b259c67979486db4cd1816234700c14a/dir_699851f087f6e6136e28f04fc8a16e7d/msr_8h.md#a7436a0f6d88d3eb717c10025325b47e8)
* [MSR\_AbortGetData()](/s-adk-5.1-programmers-guide/readme/files/dir_b259c67979486db4cd1816234700c14a/dir_699851f087f6e6136e28f04fc8a16e7d/msr_8h.md#a70fedc4ea5687982f39102e2738d8ef5)
* [MSR\_SwitchLeds()](/s-adk-5.1-programmers-guide/readme/files/dir_b259c67979486db4cd1816234700c14a/dir_699851f087f6e6136e28f04fc8a16e7d/msr_8h.md#abca7e8953c8430d80f51c867c7699fa6)

## System Setup and Requirements <a href="#sec_msr_system_setup_and_requirements" id="sec_msr_system_setup_and_requirements"></a>

### Compiler and Linker Settings <a href="#subsec_msr_compiler_and_linker_settings" id="subsec_msr_compiler_and_linker_settings"></a>

Do the following: include [msr.h](/s-adk-5.1-programmers-guide/readme/files/dir_b259c67979486db4cd1816234700c14a/dir_699851f087f6e6136e28f04fc8a16e7d/msr_8h.md) and link `libmsr.so`. Additionally you have to link `libvfisysinfo.so` and `liblog.so` (provided by ADK).

### Hardware <a href="#subsec_msr_hardware" id="subsec_msr_hardware"></a>

ADK-MSR is hardware platform agnostic and supports installation on V/OS and VOS2 terminals.

### Software <a href="#subsec_msr_software" id="subsec_msr_software"></a>

ADK-MSR is designed to be platform agnostic and will be supported on V/OS and VOS2 terminal operating systems.

### Deliverables and Deployment <a href="#subsec_msr_deliverables_and_deployment" id="subsec_msr_deliverables_and_deployment"></a>

Packages delivered (x - version number digit):

| Package name                | Description                                                       |
| --------------------------- | ----------------------------------------------------------------- |
| `msr-doc-x.x.x-xx.zip`      | Documentation                                                     |
| `msr-vos-dev-x.x.x-xx.zip`  | VOS development package, to be installed in PC build environment  |
| `msr-vos2-dev-x.x.x-xx.zip` | VOS2 development package, to be installed in PC build environment |

## Troubleshooting <a href="#sec_msr_troubleshooting" id="sec_msr_troubleshooting"></a>

### Frequently Asked Questions <a href="#subsec_msr_frequently_asked_questions" id="subsec_msr_frequently_asked_questions"></a>

Q: Some time ago, upon reviewing our test logs, you pointed out that we should not call the API [MSR\_Activate()](/s-adk-5.1-programmers-guide/readme/files/dir_b259c67979486db4cd1816234700c14a/dir_699851f087f6e6136e28f04fc8a16e7d/msr_8h.md#a1e92fd29720fecbf50da24a30c7b512f) if next we start the selection with the API [cts\_StartSelection()](/s-adk-5.1-programmers-guide/readme/files/dir_c2b6fb90cbe225a4c7f5c562006e9b78/dir_797c2eec9d33c0e51d543580c2b239ca/dir_fa87c044aa590573d847d8ba2d3b48c1/tec_8h.md#ac6699fe32fc23e90713eb617e9ff25e7) because the latter activates the reader by itself. And what about the scenario when we want to establish the MSR callback and then use the selection? Here, [MSR\_Activate()](/s-adk-5.1-programmers-guide/readme/files/dir_b259c67979486db4cd1816234700c14a/dir_699851f087f6e6136e28f04fc8a16e7d/msr_8h.md#a1e92fd29720fecbf50da24a30c7b512f) is the only way to establish such a callback. Is this a legal use case to use simultaneously the MSR callback and the selection which, in turn, may have its own callback?

A: No, this is not a legal use case. You should not establish the MSR callback if you use technology selection. This is confusing and not necessary anyway. If MSR data is available, technology selection will finish, so you get the information from TEC, no need to set MSR callback. If you even call [MSR\_GetData()](/s-adk-5.1-programmers-guide/readme/files/dir_b259c67979486db4cd1816234700c14a/dir_699851f087f6e6136e28f04fc8a16e7d/msr_8h.md#ad00fdde838f486d43be689650ab58d43) upon receiving MSR callback, TEC would most likely not be able to detect that MSR data is available and continue waiting for technology (TEC calls [MSR\_DataAvailable()](/s-adk-5.1-programmers-guide/readme/files/dir_b259c67979486db4cd1816234700c14a/dir_699851f087f6e6136e28f04fc8a16e7d/msr_8h.md#a8096fa193f035eb4b80673260d720477) and as soon as [MSR\_GetData()](/s-adk-5.1-programmers-guide/readme/files/dir_b259c67979486db4cd1816234700c14a/dir_699851f087f6e6136e28f04fc8a16e7d/msr_8h.md#ad00fdde838f486d43be689650ab58d43) is called, the former will return 'no data available'). So please do not do anything like this.

### Logging <a href="#subsec_msr_logging" id="subsec_msr_logging"></a>

You have two options to enable logging, choose one of them (if you think this is helpful, you could actually use both at once):

* Register a trace callback function with [MSR\_SetTraceCallback()](/s-adk-5.1-programmers-guide/readme/files/dir_b259c67979486db4cd1816234700c14a/dir_699851f087f6e6136e28f04fc8a16e7d/msr__common_8h.md#ac4fab89b234ae87c7da91fb529b833e0).
* Use ADK-LOG: You need to install liblog.so and create a configuration file msr\_log.conf (this is intended to be done by log control panel provided by ADK-LOG). Be sure that you activate log level LOGAPI\_INFO.

## Appendix <a href="#sec_msr_appendix" id="sec_msr_appendix"></a>

Appendix is empty.


---

# 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_msr_programmers_guide.md?ask=<question>&goal=<endgoal>
```

`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.