StarXpand SDK Manual

Step 2 Sending Printing Data: Standard Function

You will send the printing data generated in Step 1 to the printer and print it.
To send the printing data, mainly use the StarPrinter class.

Send the printing data using the procedure below.
The sample code is available at the bottom of the page. Also, refer to the sample application in the SDK.

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.

var settings = new StarConnectionSettings();
settings.interfaceType = InterfaceType.Lan;
settings.identifier = “00:11:62:00:00:01”;

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

var printer = new StarPrinter(settings);

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

try {
    var commands: string = ...

4 Call the open method to connect to the printer.

await printer.open();

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

await printer.print(commands);

6 Implement the process for when an error occurs. You can identify the error cause based on the error instance type.
Possible errors are described in the API reference of the StarPrinter class methods.
- open method
- print method

}
catch(error) {
    if (error instanceof StarIO10NotFoundError) {
        // Printer not found.
        // This may be due to the printer not being turned on or incorrect connection information.   
    }

    console.log(`Error: ${String(error)}`);
}

Memo

When the auto switch interface function is operating, the errors when connection to a printer failed are collected in StarIO10CommunicationError.
At this time, a value is also set for the autoSwitchInterfaceOpenErrors property (union type with undefined). 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.

7 Call the close method to disconnect from the printer.

finally {
    await printer.close();

8 Call the dispose method to dispose the printer instance.

await printer.dispose();

Sample code


async function print() {
    var settings = new StarConnectionSettings();
    settings.interfaceType = InterfaceType.Lan;
    settings.identifier = “00:11:62:00:00:01”;

    var printer = new StarPrinter(settings);

// Set the print data created in Step 1 to the commands variable. 
    var commands: string = ...

    try {
        await printer.open();
    } catch(error) {
        if (error instanceof StarIO10CommunicationError) {
            // If Auto Switch Interface feature is working, the autoSwitchInterfaceOpenErrors property
            // is set to a value indicating errors of each interface.
            var errorDetail = await printer.errorDetail;
            if (errorDetail.autoSwitchInterfaceOpenErrors != undefined) {
                confirmAutoSwitchInterfaceOpenErrors(errorDetail.autoSwitchInterfaceOpenErrors);
            }
        } else {
            // Handle other errors.
        }
 
        await printer.dispose();
        return;
    }
 
    try {
        await printer.print(commands);
    } catch(error) {
        if (error instanceof StarIO10UnprintableError) { 
            // If an error occurs and the print process fails, the StarIO10UnprintableException is thrown.
            // More detailed error information may be obtained with the errorCode property.
            switch (error.errorCode) {
                case StarIO10ErrorCode.DeviceHasError:
                    // An error (e.g. paper empty or cover open) has occurred in the printer.
                    // Please retry after resolving the printer error.
                    break;
                case StarIO10ErrorCode.PrinterHoldingPaper:
                    // The printer is holding paper.
                    // Remove the pre-printed paper and printing will begin.
                    break;
                default:
                    // Other errors occurred.
            }
        } else {
            // Handle other errors.
        }
    } finally {
        await printer.close();
        await printer.dispose();
    }
}

// Confirm the error that occurred when opening the printer with the Auto Switch Interface feature worked.
function confirmAutoSwitchInterfaceOpenErrors(openErrors: Map<InterfaceType,  StarIO10Error | undefined>) {
    var lanError = openErrors.get(InterfaceType.Lan);
    if (lanError != undefined) {
        if (lanError instanceof StarIO10IllegalDeviceStateError) {
            // 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.
        } else if (lanError instanceof StarIO10NotFoundError) {
            // Printer is not found.
            // Make sure that the printer is connected to the network.
        } else {
            // Other errors occurred.
        }
    }
 
    var bluetoothError = openErrors.get(InterfaceType.Bluetooth);
    if (bluetoothError != undefined) {
        if (bluetoothError instanceof StarIO10IllegalDeviceStateError) {
            // The Bluetooth function of the host device cannot be used.
            // Make sure that the host device's Bluetooth is on.
        } else if (bluetoothError instanceof StarIO10NotFoundError) {
            // Printer is not found.
            // Make sure that the printer is paired (and connected when iOS) with the host device.
        } else {
            // Other errors occurred.
        }
    }
 
    var usbError = openErrors.get(InterfaceType.Usb);
    if (usbError != undefined) {
        if (usbError instanceof StarIO10NotFoundError) {
            // Printer is not found.
            // Make sure that the host device and printer are connected with a USB cable.
        } else {
            // Other errors occurred.
        }
    }
 
    // openErrors.get(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 failures when the auto switch interface function is operating

The autoSwitchInterfaceOpenErrors property is a dictionary which uses InterfaceType as the key and StarIO10Error | undefined 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 undefined, 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. 　

StarIO10IllegalDeviceStateError : 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.
StarIO10NotFoundError : Printer not found. Check that the printer is connected to the network.

var lanError = openErrors.get(InterfaceType.Lan);
if (lanError != undefined) {
    if (lanError instanceof StarIO10IllegalDeviceStateError) {
        // 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.
    } else if (lanError instanceof StarIO10NotFoundError) {
        // 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 print method, StarIO10UnprintableError 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.

if (error instanceof StarIO10UnprintableError) { 
    // If an error occurs and the print process fails, the StarIO10UnprintableException is thrown.
    // More detailed error information may be obtained with the errorCode property.
    switch (error.errorCode) {
        case StarIO10ErrorCode.DeviceHasError:
            // An error (e.g. paper empty or cover open) has occurred in the printer.
            // Please retry after resolving the printer error.
            break;
        case StarIO10ErrorCode.PrinterHoldingPaper:
            // The printer is holding paper.
            // Remove the pre-printed paper and printing will begin.
            break;
        default:
            // Other errors occurred.
    }
} else {
    // Handle other errors.
}