StarXpand SDK for Native Manual

プリンターを検索する

手順や参照先はOSによって異なります。表示するOSを選択してください。

iOS Android

StarDeviceDiscoveryManagerを使って、非同期にプリンター検索を行います。
検索を開始すると見つかった順にイベントが発生し、 StarPrinterインスタンスを即時取得することができます。

Memo
StarPrinterインスタンスは、プリンタと通信するために必要な機能を提供するインスタンスです。
StarPrinterインスタンスを取得するには、検索を含み二通りの方法があります。

検索によって取得する方法（このページの手順8）
StarPrinterクラスのイニシャライザにinterfaceTypeとidentifierを渡して生成する方法

このStarPrinterインスタンスを使って、印刷データをプリンターに送信したり、POS周辺機器の制御を行ったりすることができます。

以下はサンプルコードの説明です。この手順を参考にプリンター検索を行ってください。
ページ下部にサンプルコードがあります。また、SDKのサンプルアプリも参考にしてください。

1検索を行うために使用するStarDeviceDiscoveryManager型の変数を用意します。

class ViewController: UIViewController, StarDeviceDiscoveryManagerDelegate {
    private var manager: StarDeviceDiscoveryManager? = nil

2検索するインターフェイスを選択します。検索したいInterfaceTypeの配列を生成してください。

func startDiscovery() {
    var interfaceTypeArray : [InterfaceType] = [InterfaceType.lan, InterfaceType.bluetooth]

3手順2で生成した配列を引数にして、StarDeviceDiscoveryManagerのインスタンスを取得します。

do {
    try manager = StarDeviceDiscoveryManagerFactory.create(interfaceTypes: interfaceTypeArray)

4検索を実行する時間を設定します。

manager?.discoveryTime = 10000

5 delegateプロパティに StarDeviceDiscoveryManagerDelegateプロトコルの実装（手順8、手順9を参照）をセットします。

manager?.delegate = self

6検索を開始するためstartDiscoveryメソッドを呼び出します。
プリンターが見つかったときに手順8で実装したデリゲートメソッドが、検索が終了したときに手順9で実装したデリゲートメソッドが呼ばれます。

try manager?.startDiscovery()

7エラー時の処理を実装します。StarIO10Errorの値によりエラーを判別できます。
発生する可能性のあるエラーはStarDeviceDiscoveryManagerFactoryクラスの createメソッド、 StarDeviceDiscoveryManagerクラスの startDiscoveryメソッドのAPIリファレンスに記載されています。

} catch StarIO10Error.illegalDeviceState(message: let message, errorCode: let errorCode) {
    if errorCode == StarIO10ErrorCode.bluetoothUnavailable {
        // Example of error: Bluetooth capability of iOS device is disabled.
        // This may be due to the host device's Bluetooth being off. 
    }
} catch {
    print("Error: \(error)")
}

8プリンターが見つかったときの処理を実装します。StarDeviceDiscoveryManagerDelegateプロトコルの manager(_ manager: StarDeviceDiscoveryManager, didFind printer: StarPrinter)メソッドをセットしてください。

func manager(_ manager: StarDeviceDiscoveryManager, didFind printer: StarPrinter) {        
    print("Found printer: \(printer.connectionSettings.identifier).")
}

9検索が終了したときの処理を実装します。StarDeviceDiscoveryManagerDelegateプロトコルの managerDidFinishDiscovery(_ manager: StarDeviceDiscoveryManager)メソッドをセットしてください。

func managerDidFinishDiscovery(_ manager: StarDeviceDiscoveryManager) {
    print("Discovery finished.")
}
}

サンプルコード


class ViewController: UIViewController, StarDeviceDiscoveryManagerDelegate {
    private var manager: StarDeviceDiscoveryManager? = nil

    func startDiscovery() {
        var interfaceTypeArray : [InterfaceType] = [InterfaceType.lan, InterfaceType.bluetooth]
        do {
            try manager = StarDeviceDiscoveryManagerFactory.create(interfaceTypes: interfaceTypeArray)
            manager?.discoveryTime = 10000
            manager?.delegate = self
            try manager?.startDiscovery()
			
        } catch StarIO10Error.illegalDeviceState(message: let message, errorCode: let errorCode) {
            if errorCode == StarIO10ErrorCode.bluetoothUnavailable {
                // Example of error: Bluetooth capability of iOS device is disabled.
                // This may be due to the host device's Bluetooth being off. 
            }
        } catch let error {
            print("Error: \(error)")
        }
    }

    func manager(_ manager: StarDeviceDiscoveryManager, didFind printer: StarPrinter) {        
        print("Found printer: \(printer.connectionSettings.identifier).")
    }
    
    func managerDidFinishDiscovery(_ manager: StarDeviceDiscoveryManager) {
        print("Discovery finished.")
    }
}

Bluetooth LEデバイスのRSSI（電波強度）を観測する

ホストデバイス近傍のスター精密製Bluetooth LEデバイス（*1）のRSSI値を、StarDeviceDiscoveryManager APIを使⽤して取得できます。
*1: 本機能に対応するスター精密製Bluetooth LEデバイスは、StarPrinterInformationBluetoothLE.rssi APIリファレンスをご参照ください。

ユースケース

スター精密製Bluetooth LEデバイスからのRSSI値を利用した、ホストデバイスが対象Bluetooth LEデバイス（およびこれに接続されたキャッシュドロアーなどの周辺機器）の近傍に存在するかの参考判定

サンプルコード


func startDiscovery() {
    let interfaceTypeArray: [InterfaceType] = [InterfaceType.bluetoothLE]
    do {
        manager = try StarDeviceDiscoveryManagerFactory.create(interfaceTypes: interfaceTypeArray)
        manager?.isEnabledFindSameDevice = true // 本プロパティをtrueにし、同一デバイスの連続検出を有効にします
        manager?.discoveryTime = 10000
        manager?.delegate = self
        try manager?.startDiscovery()
    } catch let error {
        print("Error: (error)")
    }
}

func manager(_ manager: StarDeviceDiscoveryManager, didFind printer: StarPrinter) { // 検出されたBluetooth LEデバイスは、デリゲートを通して利用できます
    if printer.connectionSettings.interfaceType == InterfaceType.bluetoothLE,
       printer.connectionSettings.identifier == "YourTargetIdentifier" {
        if let rssi = printer.information?.detail.bluetoothLE.rssi {
            print("RSSI: (rssi)") // RSSI値はこのように取得します
        }
    }
}

留意事項

RSSI値は一般的にデバイス間の距離が近いほど高くなりますが、使用する各種デバイス（ホストデバイスおよびBluetooth LEデバイス）の機種やそれぞれの固有の電波特性、Bluetooth LEデバイスの向き、また電波干渉や遮蔽等の周辺環境といった様々な要因によりその値は変動します。
本APIを利用したアプリケーションを開発される場合、実際に導入される環境を基にした十分な検証をお願いします。
ホストデバイスがキャッシュドロアー近傍に存在するかの判定としてRSSI値を使用する場合、その判定結果だけに基づいて、ユーザー操作を伴わずにキャッシュドロアーをオープンすることは、セキュリティの観点から推奨しません。
近傍に存在するかの判定において、電波干渉や遮蔽等により対象Bluetooth LEデバイスを検知できない場合を想定した実装の考慮を推奨いたします。

StarDeviceDiscoveryManagerを使って、非同期にプリンター検索を行います。
検索を開始すると見つかった順にイベントが発生し、StarPrinterインスタンスを即時取得することができます。

検索によって取得する方法（このページの手順5）
StarPrinterクラスのコンストラクタに interfaceTypeと identifierを渡して生成する方法

このStarPrinterインスタンスを使って、印刷データをプリンターに送信したり、POS周辺機器の制御を行ったりすることができます。

1検索を行うために使用するStarDeviceDiscoveryManager型の変数を用意します。

private var _manager: StarDeviceDiscoveryManager? = null

2検索するインターフェイスを選択します。検索したいInterfaceTypeのリストを生成してください。

private fun startDiscovery() {
    try {
        val interfaceTypes = listOf(InterfaceType.Lan, InterfaceType.Bluetooth)

3手順2で生成したリストを引数にして、StarDeviceDiscoveryManager のインスタンスを取得します。

_manager = StarDeviceDiscoveryManagerFactory.create(
    interfaceTypes,
    applicationContext
)

4検索を実行する時間を設定します。

_manager?.discoveryTime = 10000

5プリンターが見つかったとき、検索が終了したときの処理を実装します。
callbackプロパティに StarDeviceDiscoveryManager.Callbackインターフェイスの実装をセットしてください。 onPrinterFoundメソッドにプリンターが見つかったときの処理、onDiscoveryFinishedメソッドに検索が終了したときの処理を実装してください。

_manager?.callback = object : StarDeviceDiscoveryManager.Callback {
    override fun onPrinterFound(printer: StarPrinter) {
        Log.d("Discovery", "Found printer: ${printer.connectionSettings.identifier}.")
    }

    override fun onDiscoveryFinished() {
        Log.d("Discovery", "Discovery finished.")
    }
}

6検索を開始するためstartDiscoveryメソッドを呼び出します。
プリンターが見つかったときに手順5で実装したonPrinterFoundメソッドが、検索が終了したときにonDiscoveryFinishedメソッドが呼ばれます。

_manager?.startDiscovery()

7エラー時の処理を実装します。エラーの型によりエラー要因を判別できます。
発生する可能性のあるエラーはStarDeviceDiscoveryManagerFactoryクラスの createメソッド、 StarDeviceDiscoveryManagerクラスのstartDiscoveryメソッドのAPIリファレンスに記載されています。

} catch (e: StarIO10IllegalHostDeviceStateException) {
    if (e.errorCode == StarIO10ErrorCode.BluetoothUnavailable) {
        // Example of error: Bluetooth capability of Android device is disabled.
        // This may be due to the Android device's Bluetooth being off. 
    }
} catch (e: Exception) {
    Log.d("Discovery", "Error: ${e}")
}
}

サンプルコード


private var _manager: StarDeviceDiscoveryManager? = null
private fun startDiscovery() {
    try {
        this._manager?.stopDiscovery()
        _manager = StarDeviceDiscoveryManagerFactory.create(
            interfaceTypes,
            applicationContext
        )

        _manager?.discoveryTime = 10000
        _manager?.callback = object : StarDeviceDiscoveryManager.Callback {
            override fun onPrinterFound(printer: StarPrinter) {
                Log.d("Discovery", "Found printer: ${printer.connectionSettings.identifier}.")
            }

            override fun onDiscoveryFinished() {
                Log.d("Discovery", "Discovery finished.")
            }
        }
        _manager?.startDiscovery()
		
    } catch (e: StarIO10IllegalHostDeviceStateException) {
        if (e.errorCode == StarIO10ErrorCode.BluetoothUnavailable) {
            // Example of error: Bluetooth capability of Android device is disabled.
            // This may be due to the Android device's Bluetooth being off. 
        }
    } catch (e: Exception) {
        Log.d("Discovery", "Error: ${e}")
    }
}

Bluetooth LEデバイスのRSSI（電波強度）を観測する

ユースケース

スター精密製Bluetooth LEデバイスからのRSSI値を利用した、ホストデバイスが対象Bluetooth LEデバイス（およびこれに接続されたキャッシュドロアーなどの周辺機器）の近傍に存在するかの参考判定

サンプルコード


private var _manager: StarDeviceDiscoveryManager? = null
    private fun startDiscovery() {
        try {
            this._manager?.stopDiscovery()
            _manager = StarDeviceDiscoveryManagerFactory.create(
                listOf<InterfaceType>(InterfaceType.BluetoothLE),
                applicationContext
            )

            _manager?.isEnabledFindSameDevice = true // 本プロパティをtrueにし、同一デバイスの連続検出を有効にします
            _manager?.discoveryTime = 10000
            _manager?.callback = object : StarDeviceDiscoveryManager.Callback {
                override fun onPrinterFound(printer: StarPrinter) {
                    // 検出されたBluetooth LEデバイスは、コールバックを通して利用できます
                    if (printer.connectionSettings.interfaceType == InterfaceType.BluetoothLE &&
                    printer.connectionSettings.identifier == "YourTargetIdentifier") {
                        val rssi = printer.information?.detail?.bluetoothLE?.rssi ?: return
                        Log.d("Discovery", "RSSI: $rssi") // RSSI値はこのように取得します
                    }
                }

                override fun onDiscoveryFinished() {
                    Log.d("Discovery", "Discovery finished.")
                }
            }
            _manager?.startDiscovery()

        } catch (e: StarIO10IllegalHostDeviceStateException) {
            if (e.errorCode == StarIO10ErrorCode.BluetoothUnavailable) {
                // Example of error: Bluetooth capability of Android device is disabled.
                // This may be due to the Android device's Bluetooth being off.
            }
        } catch (e: Exception) {
            Log.d("Discovery", "Error: ${e}")
        }
    }

留意事項

RSSI値は一般的にデバイス間の距離が近いほど高くなりますが、使用する各種デバイス（ホストデバイスおよびBluetooth LEデバイス）の機種やそれぞれの固有の電波特性、Bluetooth LEデバイスの向き、また電波干渉や遮蔽等の周辺環境といった様々な要因によりその値は変動します。
本APIを利用したアプリケーションを開発される場合、実際に導入される環境を基にした十分な検証をお願いします。
ホストデバイスがキャッシュドロアー近傍に存在するかの判定としてRSSI値を使用する場合、その判定結果だけに基づいて、ユーザー操作を伴わずにキャッシュドロアーをオープンすることは、セキュリティの観点から推奨しません。
近傍に存在するかの判定において、電波干渉や遮蔽等により対象Bluetooth LEデバイスを検知できない場合を想定した実装の考慮を推奨いたします。