Appendix B - API Walk Through

CoreAPI Walk Trough

The following walks through how to create instances of devices.

• CoreAPI.createDevice à IDevice

• CoreAPI.getDeviceList à List

• CoreAPI.createPPSCRA à MTPPSCRA

These examples demonstrate methods for creating an IDevice to be used in the MagTek Universal SDK. This also shows how to establish a device specific API, which is not used with the MagTek Universal SDK.

Here, a single IDevice is established.

// Access MMS with Universal SDK using createDevice()

IDevice mtmms = CoreAPI.createDevice( 
    context,
    DeviceType.MMS, 
    ConnectionType.USB, "",
    "",
    "DynaFlex", 
    "");
mtmms.requestSignature();

Here, a list of IDevice is established. The first device is accessed at index 0.

// Acess MMS with Universal SDK using getDeviceList()

List<IDevice> mtmms = CoreAPI.getDeviceList( 
    context,
    DeviceType.MMS, 
    deviceListCallback);
mtmms[0].requestSignature();

IDevice Walk Through

The following walks through how to make use of IDevice.

• Implement device events within the class to receive events.

• CoreAPI à IDevice.

• IDevice à subscribeAll().

• IDevice à other functions.

• IDevice à startTransaction().

Example

import com.magtek.mobile.android.mtusdk.*;


// Extend the main window to receive events.
public class MainWindow implements IEventSubscriber, 
IConfigurationCallback
{

// Establish a device from CoreAPI. List<IDevice> deviceList = CoreAPI.getDeviceList(
    context, 
    deviceListCallbac);
IDevice device = deviceList[0];

/* For a list of a single device type. DeviceType deviceType = DeviceType.MMS;
List<IDevice> deviceList = CoreAPI.getDeviceList( 
    context,
    deviceType deviceListCallback);
IDevice device = deviceList[0];
*/

/* For a list of multiple device types. 
List<DeviceType> deviceTypes = null; 
deviceTypes.Add(DeviceType.MMS); 
deviceTypes.Add(DeviceType.CMS);
List<IDevice> deviceList = CoreAPI.getDeviceList( 
    context,
    deviceTypes, 
    deviceListCallback);
IDevice device = deviceList[0];
*/

/* Suscribe to events sent from the device.
These would be but not limited to: card inserted, card removed, connection state...

Set MainWindow to receive the events. */ 
boolean return = device.unsubscribeAll(this);
boolean return = device.subscribeAll(this);

/* To handle events from some other class. 
EventsVector eventsVector = new EventsVector() 
boolean return = device.unsubscribeAll(eventsVector); 
boolean return = device.subscribeAll(eventsVector);
*/

// Assign parameters for the transaction.
List<PaymentMethod> paymentMethod = new List<PaymentMethod>(); 
paymentMethod.Add(PaymentMethod.MSR); 
paymentMethod.Add(PaymentMethod.Contact); 
paymentMethod.Add(PaymentMethod.Contactless);

Transaction transaction = new Transaction(); 
transaction.setAmount(“1.00”); 
transaction.setCashBack(“0.00”); 
transaction.setEMVOnly(true); 
transaction.setPaymentMethods(paymentMethod); 
transaction.setQuickChip(false);

// Start transaction.
boolean result = device.startTransaction(transaction);

Handling Events

Application Main window may extent the

Static members

Static	Member	Value	Description
NFC_MIFARE_ULTRALIGHT	String	"nfc_mifare_ultralight"
MIFARE_CLASSIC_1K	String	"mifare_classic_1k"
MIFARE_CLASSIC_4K	String	"mifare_classic_4k"
MIFARE_DESFIRE_LIGHT	String	"mifare_desfire_light"
MIFARE_MINI	String	"mifare_mini"
MIFARE_PLUS_EV1	String	"mifare_plus_ev1"
MIFARE_PLUS_EV2	String	"mifare_plus_ev2"
MIFARE_PLUS_SE	String	"mifare_plus_se"
MIFARE_PLUS_X	String	"mifare_plus_x"
MIFARE_DESFIRE_EV1	String	"mifare_desfire_ev1"
MIFARE_DESFIRE_EV2	String	"mifare_desfire_ev2"
MIFARE_DESFIRE_EV3	String	"mifare_desfire_ev3"
MDL	String	"mdl"
TAG_REMOVED	String	"tag_removed"
FAILED	String	"failed"
IO_FAILED	String	"io_failed"
AUTHENTICATION_FAILED	String	"authentication_failed"

PersonalInfoEntry

These constructors initialize a PersonalInfoEntry object.

• Call startPersonalInfoEntry().

• At OnEvent():TouchscreenPersonalInfoEntry, build the object.

PersonalInfoEntry PersonalInfoEntryBuilder.GetPersonalInfoEntry( 
DeviceType deviceType, 
byte[] dataBytes);

new PersonalInfoEntry( 
    byte[] data, 
    CaptureType dataType, 
    bool encrypted,
    ); 

new PersonalInfoEntry( 
        byte[] data, 
        CaptureType dataType, 
        bool encrypted, 
        byte encryptionType, 
        byte[] ksn
        );

Member	Description
deviceType	Type of device.
dataBytes	Data to pass in after set from OnEvent().
data()	Returns the data payload.
dataType()	Returns the capture type.
encrypted()	Returns the encryption status. false = data is not encrypted true = data is encrypted
encryptionType()	Returns the encryption type.
ksn()	Returns the Key Serial Number.

Return Value:

Returns an instance of PersonalInfoEntry.

IEventSubscriber Delegates or can be extended by a separate class. This example uses a separate class and demonstrates how to parse for the various event types.

Example

// A class to handle events.
public class EventsVector implements IEventSubscriber
{
    public void OnEvent(EventType eventType, IData data)
    {
        switch (eventType)
        {

Various events are separately shown below

case ConnectionState:
// Parse for the ConnectionState ConnectionState value =
ConnectionStateBuilder.GetValue(data.StringValue());

break;

case DeviceResponse:

break;

case DeviceExtendedResponse:

break;

case DeviceNotification:

break;

case CardData:

break;

case TransactionStatus:
// Parse for the transaction status code and detail. 
TransactionStatus status = 
TransactionStatusBuilder.GetStatusCode(data.StringValue());

string statusDetail = TransactionStatusBuilder.GetStatusDetail(data.StringValue());

break;

case DisplayMessage:

String message;
// Get the message. if (data != null)
{
message = System.Text.Encoding.UTF8.GetString(data);
}
break;

case InputRequest:

break;

case AuthorizationRequest:

// Forward ARQC to processor.
/* data[0..1] – ARQC length
data[2..n] – remainder contains the ARQC TLV object
*/

IData processorARPC = new 
BaseData(sendForAuthorization(data.ByteArray()));

// Send authorization to device when not in QuickChip mode. 
if (transaction.QuickChip == false)
{
device.sendAuthorization(procesorARPC.ByteArray());
}

break;

case TransactionResult

/* data[0] – Signature Required
    data[1..2] – Batch Data length
    data[3..n] – remainder contains the Batch Data TLV object
*/

// Parse the TLV from data[].
.
// Abstract Approval status from TLV tag “DFDF1A”.
.
// Abstract Signature Required status from TLV tag data[0].
.

break;

case PINBlock:

break;

case Signature:

break;

IDeviceControl Walk Through

The following walks through how to make use of IDeviceControl.

• IDevice --> IDeviceControl.· IDeviceControl à open().

• IDeviceControl --> other functions.

• IDeviceControl --> close().

Example

// Establish a device from CoreAPI.
List<IDevice> deviceList = CoreAPI.getDeviceList(); IDevice device = deviceList[0];

// Establish a deviceControl from device.
IDeviceControl deviceControl = device.getDeviceControl();

// Open the device, then use the IDeviceControl functions. deviceControl.open();

. . .

// Close the device. deviceControl.close();

ConnectionInfo Walk Through

The following walks through how to make use of ConnectionInfo.

• IDevice --> ConnectionInfo.

• ConnectionInfo --> getAddress()

• ConnectionInfo --> getConnectionType()

• ConnectionInfo --> getDeviceType() Example

Example

// Establish a device from CoreAPI.
List<IDevice> deviceList = CoreAPI.getDeviceList(); 
IDevice device = deviceList[0];

// Establish a ConnectionInfo from device.
ConnectionInfo connectionInfo = device.getConnectionInfo();

// Retrieve address, connectionType, and deviceType. 
String address = connectionInfo.getAddress();
ConnectionType connectionType = connectionInfo.getConnectionType(); 
DeviceType deviceType = connectionInfo.getDeviceType();

IDeviceCapabilities Walk Through

The following walks through how to make use of IDeviceCapabilities.

• IDevice à IDeviceCapabilities.

• IDeviceCapabilities à BatteryBackedClock() to check if date/time should be set.

• IDeviceCapabilities à PaymentMethods() to check card types supported.

• IDeviceCapabilities à other functions.

 // Establish a device from CoreAPI.
List<IDevice> deviceList = CoreAPI.getDeviceList(); 
IDevice device = deviceList[0];

// Establish a IDeviceCapabilities from device. 
IDeviceCapabilities capabilities = device.getCapabilities();


// Retrieve device capabilities.
boolean batteryBackedClock = capabilities.BatteryBackedClock(); 
if (batteryBackedClock)
{
// Call IDeviceControl.setDateTime().
}

// Retrieve supported card payment methods.
List<PaymentMethod> paymentMethods = capabilities.PaymentMethods();

. . .

IDeviceConfiguration Walk Through

The following walks through how to make use of IDeviceConfiguration.

• IDevice --> getDeviceConfiguration().

• IDeviceConfiguration --> updateFirmware().

• IDeviceConfiguration --> getConfiguration().

• IDeviceConfiguration --> setConfiguration().

• IDeviceConfiguration --> other functions.

Example

// Establish a device from CoreAPI.
List<IDevice> deviceList = CoreAPI.getDeviceList(); 
IDevice device = deviceList[0];

IDeviceConfiguration deviceConfiguration = 
    device.getDeviceConfiguration();

/* To handle events from some other class. ConfigCallBacks 
configCallBacks = new ConfigCallBacks();
*/

// Update firmware.
byte[] data = getDataFromURI(uri);
int return = deviceConfiguration.updateFirmware(1, data, this);

/* Get configuration.
    Device-Driven Fallback OID = 1.2.1.1.1.1
            contructed OID = E2 08 E1 06 E1 04 E1 02 C1 00
    Note: first digit of OID is ommited in the construction and instead is passed in the configType.
*/
byte configType = 0x01;
data = new byte[] {0xE2,0x08,0xE1,0x06,0xE1,0x04,0xE1,0x02,0xC1,0x00
};
byte[] response = devConfig.getConfigInfo(configType, data);


/* Set configuation.
    Device-Driven Fallback OID is 1.2.1.1.1.1
        Disabled contructed OID = E2 09 E1 07 E1 05 E1 03 C1 01 00
            Enabled contructed OID = E2 09 E1 07 E1 05 E1 03 C1 01 01
    Note: first digit of OID is ommited in the construction and instead 
is passed in the configType.

*/
data = new byte[]
{0xE2,0x09,0xE1,0x07,0xE1,0x05,0xE1,0x03,0xC1,0x01,0x00 };
result = devConfig.getConfigInfo(configType, data);

Handling Events

Application Main window may extent the IConfigurationCallback Delegates or can be extended by a separate class. This example uses a separate class and demonstrates how to parse for the various events.

Example

// A class to handle configuration callback events.
public class ConfigCallbacks implements IConfigurationCallback
{

    public void OnProgress(int progress)
    {
        /* Handle progress.
            Progress is complete when progress = 100 */
    }

public void OnResult(StatusCode status, byte[] data)
{
    /* Handle result.
        A configuration process is complete when 
        status = StatusCode.Success */
}

public IResult OnCalculateMAC(byte macType, byte[] data)
{
    IResult result = new Result(StatusCode.UNAVAILABLE); 
    byte[] macBytes = null;
    
    DeviceType deviceType =
        device.getConnection Info().getDeviceType();

    switch (deviceType)
    {
        case DeviceType.MMS:
            macBytes = getDynaFlexMAC(macType, data); 
            break;
    }

    if (macBytes != null)
    {
        result = new Result(StatusCode.SUCCESS); 
        result.Data = new BaseData(macBytes);
    }

    return result;
    }

}