StarXpand SDK for iOS/Android Developer's Manual Ver. 1.8.0

Last update: November 1, 2024

Step 2 Send Printing Data: Standard Function

Send the printing data generated in Step 1 to the printer to print.

The procedure varies depending on the OS. Select the OS to display.

iOS Android

Send the printing data using the procedure below.
The sample code is available at the bottom of the page.

1 Create the printer destination information.
Set interfaceType, which is used for communication, and identifier, which specifies the destination.
If the destination printer has already been searched for in Search for Printer, this setting is unnecessary.
Set the StarPrinter instance acquired with the manager(_ manager: StarDeviceDiscoveryManager, didFind printer: StarPrinter) method in the printer variable in Step2.

let starConnectionSettings = StarConnectionSettings(interfaceType: .lan, identifier: "00:11:62:00:00:01")

2 Provide the printer destination information to acquire the StarPrinter instance.

let printer = StarPrinter(starConnectionSettings)

3 Set the printing data created in Step 1 in the commands variable.

Task {
    do {
        let command = ...

4 Call the open method to connect to the printer.

try await printer.open()

5 Call the close method with the defer block to disconnect from the printer after sending the printing data.

defer {
    Task {
        await printer.close()
    }
}

6 Call the print method to send the printing data to the printer.

try await printer.print(command: command)

7 Identify the error based on the StarIO10Error value and implement the process for when an error occurs.
Possible errors are described in the API reference of the open method and print method of the StarPrinter class.

} catch StarIO10Error.notFound(message: let message, errorCode: let errorCode) {
    // Printer not found.
    // This may be due to the printer not being turned on or incorrect connection information.
} catch let error {
    print("Error: \(error)")
}
}

Memo

  • When the auto switch interface function is operating, the errors when connection to a printer failed are collected in StarIO10Error.communication.
    At this time, a value is also set for the autoSwitchInterfaceOpenErrors property (optional). By checking this value, it is possible to identify the cause of the connection trial failure for each interface using the auto switch interface function.
    See here for details.
  • It may be possible to acquire a more precise cause of the error from the errorCode property.
    Here we will use an error that occurred with the print method as an example and explain in detail.
Sample code

func print() {
    let starConnectionSettings = StarConnectionSettings(interfaceType: .lan,
                                                            identifier: “00:11:62:00:00:01”)
    let printer = StarPrinter(starConnectionSettings)

    // Set the print data created in Step 1 to the command variable.
    let commands = …
    
    Task {
        do {
            try await printer.open()
        } catch StarIO10Error.communication(message: let message, errorCode: let errorCode) {
            // If Auto Switch Interface feature is working, the autoSwitchInterfaceOpenErrors property
            // is set to a value indicating errors of each interface.
            if let openErrors = printer.errorDetail.autoSwitchInterfaceOpenErrors {
                confirmAutoSwitchInterfaceOpenErrors(openErrors)
            }
            return
        } catch let error {
            print(error)
            return
        }
        
        do {
            defer {
                Task {
                    await printer.close()
                }
            }
            
            try await printer.print(command: commands)
        } catch StarIO10Error.unprintable(message: let message, errorCode: let errorCode, status: let status) {
            // If an error occurs and the print process fails, the StarIO10Error.unprintable is thrown.
            // More detailed error information may be obtained with the errorCode property.
            switch errorCode {
            case .deviceHasError:
                // An error (e.g. paper empty or cover open) has occurred in the printer.
                // Please retry after resolving the printer error.
                print("An error (e.g. paper empty or cover open) has occurred in the printer.")
            case .printerHoldingPaper:
                // The printer is holding paper.
                // Remove the pre-printed paper and printing will begin.
                print("The printer is holding paper.")
            default:
                // Other errors occurred.
                print("Other errors occurred.")
            }
        } catch let error {
            // Catch other exceptions.
        }
    }
}

// Confirm the error that occurred when opening the printer with the Auto Switch Interface feature worked.
func confirmAutoSwitchInterfaceOpenErrors(_ openErrors: Dictionary<InterfaceType, StarIO10Error?>) {
    if let lanError = openErrors[.lan],
       let lanError = lanError {
        switch lanError {
        case .illegalDeviceState(message: let message, errorCode: let errorCode):
            // The network function of the host device cannot be used.
            // Make sure that the host device's Wi-Fi is on and
            // is connected to the network.
            print("illegalDeviceStat Error: \(lanError)")
        case .notFound(message: let message, errorCode: let errorCode):
            // Printer is not found.
            // Make sure that the printer is connected to the network.
            print("notFound Error: \(lanError)")
        default:
            // Other errors occurred.
            print("Other Error: \(lanError)")
        }
    }
    
    if let bluetoothError = openErrors[.bluetooth],
       let bluetoothError = bluetoothError {
        switch bluetoothError {
        case .illegalDeviceState(message: let message, errorCode: let errorCode):
            // The Bluetooth function of the host device cannot be used.
            // Make sure that the host device's Bluetooth is on.
            print("illegalDeviceState Error: \(bluetoothError)")
        case .notFound(message: let message, errorCode: let errorCode):
            // Printer is not found.
            // Make sure that the printer is paired and connected with the host device.
            print("notFound Error: \(bluetoothError)")
        default:
            // Other errors occurred.
            print("Other Error: \(bluetoothError)")
        }
    }
    
    if let usbError = openErrors[.usb],
       let usbError = usbError {
        switch usbError {
        case .notFound(message: let message, errorCode: let errorCode):
            // Printer is not found.
            // Make sure that the host device and printer are connected with a USB cable.
            print("notFound Error: \(usbError)")
        default:
            // Other errors occurred.
            print("Other Error: \(usbError)")
        }
    }
    
    // openErrors[InterfaceType.bluetoothLE] is always nil, because there is
    // no Auto Switch Interface feature enabled model that supports bluetoothLE InterfaceType.
}



Method of acquiring the cause of failures when the auto switch interface function is operating

The autoSwitchInterfaceOpenErrors property is a dictionary which uses InterfaceType as the key and StarIO10Error? as the value. It stores the exceptions when a connection trial fails with each interface when the auto switch interface function is operating. When the value is nil, either the printer does not include that interface, or else a connection trial using that interface was not executed.
For example, the causes of connection failure with a LAN interface can be identified as shown below.
  •  StarIO10Error.illegalDeviceState : The host device network function cannot be used. Check that the host device Wi-Fi is ON and that it is connected to the network.
  •  StarIO10Error.notFound : Printer not found. Check that the printer is connected to the network.
if let lanError = openErrors[.lan],
    let lanError = lanError {
    switch lanError {
    case .illegalDeviceState(message: let message, errorCode: let errorCode):
        // The network function of the host device cannot be used.
        // Make sure that the host device's Wi-Fi is on and
        // is connected to the network.
        print("illegalDeviceStat Error: \(lanError)")
    case .notFound(message: let message, errorCode: let errorCode):
        // Printer is not found.
        // Make sure that the printer is connected to the network.
        print("notFound Error: \(lanError)")
    default:
        // Other errors occurred.
        print("Other Error: \(lanError)")
    }
}        

For the overall process used to acquire the failure cause, refer to the confirmAutoSwitchInterfaceOpenErrors method of the Sample code.


Method of acquiring the error details information using StarIO10ErrorCode

It may be possible to acquired a more precise cause of the error from the errorCode property.
As an example, when the print process failed with the print method, StarIO10Error.unprintable is thrown. At this time, it is possible to check the errorCode property and correct each error cause as shown below.
  •  deviceHasError : The printer is out of paper, the cover is open, or there is a similar error status. Once the error state is cleared, then retry printing.
  •  printerHoldingPaper : The printer is holding the paper. Printing will start when the paper that was previously printed is removed.
} catch StarIO10Error.unprintable(message: let message, errorCode: let errorCode, status: let status) {
    // If an error occurs and the print process fails, the StarIO10Error.unprintable is thrown.
    // More detailed error information may be obtained with the errorCode property.
    switch errorCode {
    case .deviceHasError:
        // An error (e.g. paper empty or cover open) has occurred in the printer.
        // Please retry after resolving the printer error.
        print("An error (e.g. paper empty or cover open) has occurred in the printer.")
    case .printerHoldingPaper:
        // The printer is holding paper.
        // Remove the pre-printed paper and printing will begin.
        print("The printer is holding paper.")
    default:
        // Other errors occurred.
        print("Other errors occurred.")
    }
} catch let error {
    // Catch other exceptions.
}
		

Send the printing data using the procedure below.
The sample code is available at the bottom of the page.

1 Create the printer destination information.
Set interfaceType, which is used for communication, and identifier, which specifies the destination.
If the destination printer has already been searched for in Search for Printer, this setting is unnecessary.
Set the StarPrinter instance acquired with the onPrinterFound method in the printer variable in Step2.

val settings = StarConnectionSettings(InterfaceType.Lan, "00:11:62:00:00:01")

2 Provide the printer destination information to acquire the StarPrinter instance.

val printer = StarPrinter(settings, applicationContext)

3 Set the printing data created in Step 1 in the commands variable.

val job = SupervisorJob()
val scope = CoroutineScope(Dispatchers.Default + job)

scope.launch {
    try {
        val commands = ...

4 Call the openAsync method to connect to the printer.

printer.openAsync().await()

5 Call the printAsync method to send the printing data to the printer.

printer.printAsync(commands).await()

6 Identify the error cause based on the error type and implement the process for when an error occurs.
Possible errors are described in the API reference of the openAsync method and printAsync method of the StarPrinter class.

} catch (e: StarIO10NotFoundException) {
    // Printer not found.
    // This may be due to the printer not being turned on or incorrect connection information.
} catch (e: Exception) {
    Log.d("Printing", "Error: ${e}")

Memo

  • When the auto switch interface function is operating, the errors when connection to a printer failed are collected in StarIO10CommunicationException.
    At this time, a value is also set for the autoSwitchInterfaceOpenErrors property (optional). By checking this value, it is possible to identify the cause of the connection trial failure for each interface using the auto switch interface function.
    See here for details.
  • It may be possible to acquire a more precise cause of the error from the errorCode property.
    Here we will use an error that occurred with the printAsync method as an example and explain in detail.


7 Call the closeAsync method to disconnect from the printer.

} finally {
printer.closeAsync().await()
}
}
Sample code

fun print() {
    val settings = StarConnectionSettings(InterfaceType.Lan, “00:11:62:00:00:01”)
    val printer = StarPrinter(settings, applicationContext)

    val job = SupervisorJob()
    val scope = CoroutineScope(Dispatchers.Default + job)

// Set the print data created in Step 1 to the commands variable.
    val commands = …

    scope.launch {
        try {
            printer.openAsync().await()
        } catch (e: StarIO10CommunicationException) {
            // If Auto Switch Interface feature is working, the autoSwitchInterfaceOpenErrors property
            // is set to a value indicating errors of each interface.
            printer.errorDetail.autoSwitchInterfaceOpenErrors?.let { it ->
                confirmAutoSwitchInterfaceOpenErrors(it)
            }
            return@launch
        } catch (e: Exception) {
            // Catch other exceptions.
            return@launch
        }

        try {
            printer.printAsync(commands).await()
        } catch (e: StarIO10UnprintableException) {
            // If an error occurs and the print process fails, the StarIO10UnprintableException is thrown.
            // More detailed error information may be obtained with the errorCode property.
            when (e.errorCode) {
                StarIO10ErrorCode.DeviceHasError -> {
                    // An error (e.g. paper empty or cover open) has occurred in the printer.
                    // Please retry after resolving the printer error.
                }
                StarIO10ErrorCode.PrinterHoldingPaper -> {
                    // The printer is holding paper.
                    // Remove the pre-printed paper and printing will begin.
                }
                else -> {
                    // Other errors occurred.
                }
            }
        } catch (e: Exception) {
            // Catch other exceptions.
        } finally {
            printer.closeAsync().await()
        }
    }
}
	  
// Confirm the error that occurred when opening the printer with the Auto Switch Interface feature worked.
fun confirmAutoSwitchInterfaceOpenErrors(openErrors: Map<InterfaceType, StarIO10Exception?>) {
    openErrors[InterfaceType.Lan]?.let {
        when (it) {
            is StarIO10IllegalHostDeviceStateException -> {
                // The network function of the host device cannot be used.
                // Make sure that the host device's Wi-Fi is on and
                // is connected to the network.
            }
            is StarIO10NotFoundException -> {
                // Printer is not found.
                // Make sure that the printer is connected to the network.
            }
            else -> {
                // Other errors occurred.
            }
        }
    }

    openErrors[InterfaceType.Bluetooth]?.let {
        when (it) {
            is StarIO10IllegalHostDeviceStateException -> {
                // The Bluetooth function of the host device cannot be used.
                // Make sure that the host device's Bluetooth is on.
            }
            is StarIO10NotFoundException -> {
                // Printer is not found.
                // Make sure that the printer is paired with the host device.
            }
            else -> {
                // Other errors occurred.
            }
        }
    }

    openErrors[InterfaceType.Usb]?.let {
        when (it) {
            is StarIO10NotFoundException -> {
                // Printer is not found.
                // Make sure that the host device and printer are connected with a USB cable.
            }
            else -> {
                // Other errors occurred.
            }
        }
    }

    // openErrors[InterfaceType.BluetoothLE] is always null, because there is
    // no Auto Switch Interface feature enabled model that supports BluetoothLE InterfaceType.
}



Method of acquiring the cause of connection trial failures when the auto switch interface function is operating

The autoSwitchInterfaceOpenErrors property is a dictionary which uses InterfaceType as the key and StarIO10Exception? as the value. It stores the exceptions when a connection trial fails with each interface when the auto switch interface function is operating.
When the value is null, either the printer does not include that interface, or else a connection trial using that interface was not executed.
For example, the causes of connection failure with a LAN interface can be identified as shown below.
  •  StarIO10IllegalHostDeviceStateException : The host device network function cannot be used. Check that the host device Wi-Fi is ON and that it is connected to the network.
  •  StarIO10NotFoundException : Printer not found. Check that the printer is connected to the network.
openErrors[InterfaceType.Lan]?.let {
    when (it) {
        is StarIO10IllegalHostDeviceStateException -> {
            // The network function of the host device cannot be used.
            // Make sure that the host device's Wi-Fi is on and
            // is connected to the network.
        }
        is StarIO10NotFoundException -> {
            // Printer is not found.
            // Make sure that the printer is connected to the network.
        }
        else -> {
            // Other errors occurred.
        }
    }
}        
        

For the overall process used to acquire the failure cause, refer to the confirmAutoSwitchInterfaceOpenErrors method of the Sample code.


Method of acquiring the error details information using StarIO10ErrorCode

It may be possible to acquired a more precise cause of the error from the errorCode property.
As an example, when the print process failed with the printAsync method, StarIO10UnprintableException is thrown. At this time, it is possible to check the errorCodeproperty and correct each error cause as shown below.  
  •  DeviceHasError : The printer is out of paper, the cover is open, or there is a similar error status. Once the error state is cleared, then retry printing.
  •  PrinterHoldingPaper : The printer is holding the paper. Printing will start when the paper that was previously printed is removed.
} catch (e: StarIO10UnprintableException) {
    // If an error occurs and the print process fails, the StarIO10UnprintableException is thrown.
    // More detailed error information may be obtained with the errorCode property.
    when (e.errorCode) {
        StarIO10ErrorCode.DeviceHasError -> {
            // An error (e.g. paper empty or cover open) has occurred in the printer.
            // Please retry after resolving the printer error.
        }
        StarIO10ErrorCode.PrinterHoldingPaper -> {
            // The printer is holding paper.
            // Remove the pre-printed paper and printing will begin.
        }
        else -> {
            // Other errors occurred.
        }
    }
} catch (e: Exception) {
    // Catch other exceptions.
}