> For the complete documentation index, see [llms.txt](https://developer.magtek.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.magtek.com/sdks-and-tools/universal-sdk-documentation/ios/appendices/appendix-a-api-walk-through.md).

# Appendix A - API Walk Through

### CoreAPI Walk Through

The following walks through how to create instances of a device.

* CoreAPI.createDevice() --> IDevice
* CoreAPI.setDeviceType()
* CoreAPI.startScanningForPeripherals --> onDeviceList()

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.

{% code overflow="wrap" %}

```
// Access MMS with Universal SDK using createDevice()

var mtmms: IDevice = CoreAPI.createDevice( 
        MTU_DeviceType_MMS,
        connection: MTU_ConnectionType_ WEBSOCKET, 
        address: "ws://b123456.magtek.com",
        model: "DynaFlex", 
        name: webSocketAddress, 
        serial: "B123456", 
        cert: Certificate)
```

{% endcode %}

**BLE device**

{% code overflow="wrap" %}

```
// Access BLE device with Universal SDK

private let mtusdkShared = CoreAPI.shared() 
mtusdkShared.setDeviceType(MTU_DeviceType_MMS, andConnectionType: MTU_ConnectionType_BLUETOOTH_LE_EMV)

mtusdkShared.mtuSDKDelegate = self 
mtusdkShared.startScanningForPeripherals()
```

{% endcode %}

{% code overflow="wrap" %}

```
// Acess onDeviceList()

func onDeviceList(_ instance: Any, withConnectionType: 
MTU_ConnectionType, deviceList: [Any])
{
        if let devices = deviceList as? [IDevice] { 
                deviceAddressList = []
        }
}
```

{% endcode %}

iAP2 Lightning device.

{% code overflow="wrap" %}

```
// Acess iAP2 device with Universal SDK

private let mtusdkShared = CoreAPI.shared() 
mtusdkShared.setDeviceType(MTU_DeviceType_MMS, andConnectionType: MTU_ConnectionType_EXTERNAL_ACCESSORY)

mtusdkShared.setupEADeviceProtocolString(MTUConstant.dynaFlex2GoProtoc 
olString)
mtusdkShared.mtuSDKDelegate = self 
mtusdkShared.turnEAAccessoryConnectionNotificationsOn() mtusdkShared.showConnectedEAAccessoryIfAny()
```

{% endcode %}

{% code overflow="wrap" %}

```
// Acess onDeviceList()

func onDeviceList(_ instance: Any, withConnectionType: 
MTU_ConnectionType, deviceList: [Any])
{
        if let devices = deviceList as? [IDevice] { 
                deviceAddressList = []
        }
}
```

{% endcode %}

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**

{% code overflow="wrap" %}

```
// Extend the main window to receive events. @interface MTUSCK_DynaFlex : <IEventSubscriber, IConfigurationCallback>

// Establish a device from CoreAPI.
var device: IDevice = CoreAPI.createDevice( 
        MTU_DeviceType_MMS, 
        connection:MTU_ConnectionType_ WEBSOCKET, 
        address:"ws://b123456.magtek.com",
        "",
        "DynaFlex", 
        "",
        cert:Certificate)


/* 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. */ var result: Bool = device.subscribeAll(self)

// Assign parameters for the transaction.
var transaction: ITransaction = ITransaction( Amount:“1.00”,
CashBack:“0.00”, TransactionType:0, Timeout:30,
For:MTU_PaymentMethod_MSR | MTU_PaymentMethod_Contact | MTU_PaymentMethod_Contactless,
QuickChip:true
)

// Start transaction.
result = device.startTransaction(transaction)
@interface MTUSCK_DynaFlex : <IEventSubscriber, IConfigurationCallback>

func onEvent(_ eventType: MTU_EventType, data: IData!)
{
switch eventType
{
```

{% endcode %}

#### Handling Events <a href="#a.2.1_handling_events" id="a.2.1_handling_events"></a>

Application Main window may extent the IEventSubscriber. This example demonstrates how to parse for the various event types.

**Example**

{% code overflow="wrap" %}

```
@interface MTUSCK_DynaFlex : <IEventSubscriber, 
IConfigurationCallback>

func onEvent(_ eventType: MTU_EventType, data: IData!)
{
        switch eventType
        {
```

{% endcode %}

**Various events are separately shown below.**

{% code overflow="wrap" %}

```
case MTU_EventType_ConnectionState:
// Parse for the ConnectionState
var value: MTU_ConnectionState = ConnectionStateBuilder.GetValue(data)

break;
```

{% endcode %}

{% code overflow="wrap" %}

```
case MTU_EventType_DeviceResponse:

break;
```

{% endcode %}

{% code overflow="wrap" %}

```
case MTU_EventType_DeviceExtendedResponse:

break;
```

{% endcode %}

<pre data-overflow="wrap"><code><strong>case MTU_EventType_DeviceNotification:
</strong>
break;
</code></pre>

{% code overflow="wrap" %}

```
case MTU_EventType_CardData:

break;
```

{% endcode %}

{% code overflow="wrap" %}

```
case MTU_EventType_DisplayMessage:

// Get the message.

var message: NSString = data.StringValue
break;
```

{% endcode %}

{% code overflow="wrap" %}

```
case MTU_EventType_InputRequest:

break;
```

{% endcode %}

{% code overflow="wrap" %}

```
case MTU_EventType_AuthorizationRequest:

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

var ARQC: IData = IData.dataWithData(data.ByteArray)

// App function to send the request to the processor. 
var ARPC: NSString = 
sendARQCToProcessorForApproval(ARQC.data.ByteArray);

// Send authorization to device when not in QuickChip mode. 
var ARPCTLV: IData = IData.alloc(init);
ARPCTLV.StringValue = "FF7413DFDF250742363243413546FA067004” + ARPC;

if transaction.QuickChip == false
{
device.sendAuthorization(ARPCTLV)
}

break;
```

{% endcode %}

{% code overflow="wrap" %}

```
case MTU_EventType_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 at data[0].

break;
```

{% endcode %}

{% code overflow="wrap" %}

```
case EventType.PINData:

break; 
```

{% endcode %}

{% code overflow="wrap" %}

```
case MTU_EventType_Signature:

break;
```

{% endcode %}

{% code overflow="wrap" %}

```
 case MTU_EventType_TransactionStatus:

/*
Transaction status enumeration is build from the TransactionStatusBuilder.

*/
var status: MTU_TransactionStatus = TransactionStatusBuilder. 
GetStatusCode(data.StringValue);

if status == MTU_TransactionStatus_CardSwiped
{
    //
}
if status == MTU_TransactionStatus_CardInserted
{
    //
}

if status == MTU_TransactionStatus_TransactionApproved
{
    //
}

break;
```

{% endcode %}

### IDeviceControl Walk Through <a href="#a.3_idevicecontrol_walk_through" id="a.3_idevicecontrol_walk_through"></a>

The following walks through how to make use of IDeviceControl.

* IDevice --> IDeviceControl.
* IDeviceControl --> open().
* IDeviceControl --> other functions.
* IDeviceControl --> close().

Example

{% code overflow="wrap" %}

```
// Establish a deviceControl from device.
var deviceControl: IDeviceControl = device.getDeviceControl

// Open the device, then use the IDeviceControl functions. var result: BOOL = deviceControl.open()

. . .

// Close the device.
result = deviceControl.close()
```

{% endcode %}

### ConnectionInfo Walk Through <a href="#a.4_connectioninfo_walk_through" id="a.4_connectioninfo_walk_through"></a>

The following walks through how to make use of ConnectionInfo.

* ConnectionInfo --> getAddress()
* ConnectionInfo --> getConnectionType()
* ConnectionInfo --> getDeviceType() Example

{% code overflow="wrap" %}

```
// Establish a ConnectionInfo from device.
var connectionInfo: ConnectionInfo = device.getConnectionInfo()

// Retrieve address, connectionType, and deviceType. 
var address: NSString = connectionInfo.getAddress()
var connectionType: MTU_ConnectionType = connectionInfo
.getConnectionType()
var deviceType: MTU_DeviceType = connectionInfo.getDeviceType()
```

{% endcode %}

### IDeviceCapability Walk Through <a href="#a.5__idevicecapability_walk_through" id="a.5__idevicecapability_walk_through"></a>

The following walks through how to make use of IDeviceCapability.

* IDeviceCapability à BatteryBackedClock() to check if date/time should be set.
* IDeviceCapability à PaymentMethods() to check card types supported.
* IDeviceCapability à other functions.

{% code overflow="wrap" %}

```
// Establish a IDeviceCapabilities from device. DeviceCapabilities* capabilities = device.getDeviceCapability

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

// Retrieve supported card payment methods.

MTU_PaymentMethod paymentMethods = capabilities.PaymentMethods
```

{% endcode %}

### IDeviceConfiguration Walk Through <a href="#a.6_ideviceconfiguration_walk_through" id="a.6_ideviceconfiguration_walk_through"></a>

The following walks through how to make use of IDeviceConfiguration.

* IDevice à getDeviceConfiguration().
* IDeviceConfiguration à updateFirmware().
* IDeviceConfiguration à getConfiguration().
* IDeviceConfiguration à setConfiguration().
* IDeviceConfiguration à other functions.

**Example**

{% code overflow="wrap" %}

```
IDeviceConfiguration* devConfig = device.getDeviceConfiguration

IDeviceControl* devControl = device.getDeviceControl result = devControl.open()
// Update firmware. 
var error: IData*
var fileData: NSData = NSData.dataWithContentsOfFile( 
"/Users/UserName/DynaFlex/fw.bin",
options: NSDataReadingUncached, 
error: &error);

var return: Int = devConfig.updateFirmware(1, data: fileData, 
callback: self)

/* 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.
*/
var configType: Byte = 1;
var str: NSString = "E208E106E104E102C100"
var data: NSData= HexUtil.getBytesFromHexString(str)
var response: NSData = 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.
*/
configType = 1
str = "E209E107E105E103C10101"
data NSData = HexUtil.getBytesFromHexString(str)
return = devConfig.setConfigInfo(configType, data, callback:self)
```

{% endcode %}

#### Handling Events <a href="#a.6.1_handling_events" id="a.6.1_handling_events"></a>

Application Main window may extent the IConfigurationCallback Delegates. This example demonstrates how to parse for the various events.

**Example**

{% code overflow="wrap" %}

```
func onProgress(_ progressValue: Int32)
{

}
```

{% endcode %}

{% code overflow="wrap" %}

```
func onResult(_ status: MTU_StatusCode, data: Data)
{
/* Handle result.
A configuration process is complete when status = MTU_StatusCode_Success */
}
```

{% endcode %}

<pre data-overflow="wrap"><code> func OnCalculateMAC (_ macType: UInt8, data: Data) -> IResult
{
<strong>    //Calculate MAC.
</strong>}
</code></pre>


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.magtek.com/sdks-and-tools/universal-sdk-documentation/ios/appendices/appendix-a-api-walk-through.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.