English site 日本語サイト

6.1. ISCBBuilder 移行ガイド（StarPRNT V5搭載機能）

本ページは、プリンターモデル依存を最小限に抑えることを目的とした ISCBBuilder 移行ガイドです。

ISCBBuilder とは、従来のバイナリ形式でのコマンド生成ではなくヒューマンリーダブルなコマンド生成を可能にする機能で、StarPRNT V5.0以降の拡張ライブラリ（以降、 StarIO_Extension ）に搭載しています。

今までは開発者がプリンターエミュレーションの仕様を理解した上でコマンドを生成しなければいけませんでしたが、本機能により学習コストを抑えることができ、機種追加時の工数削減も期待できます。

本ページを参考に ISCBBuilder をご活用ください。

6.1.1. 必要な作業内容一覧

ISCBBuilder への移行とプリンターモデルの追加に必要な作業は以下です。

1. StarIO_Extension の導入

2. APIとコマンド作成方法の変更

3. Emulationの指定

4. portNameの指定

重要

プリンターモデルの組み合わせによっては、 portSettings指定の変更 も必要になります。

6.1.2. StarIO_Extension の導入

プロジェクトに StarIO_Extension が組み込まれていることを確認してください。 各ライブラリは同一SDKバージョンの物をご利用ください。

1. CocoaPodsを使用する場合

PodFile

pod 'StarIO', 'StarIOVersion'
pod 'StarIO_Extension', 'StarIOExtensionVersion'
pod 'SMCloudServices', 'SMCloudServicesVersion'

2. Frameworkを使用する場合

下記Frameworkが組み込まれていることを確認してください。

1. StarIO.xcframework

2. StarIO_Extension.xcframework

3. SMCloudServices.xcframework

ライブラリ導入手順の詳細は、 ライブラリ追加方法 に記載しています。

6.1.3. APIとコマンド作成方法の変更方法（ICommandBuilderの導入）

全体フローの違い

下記フローに示すように、 ISCBBuilder の導入にコマンド生成部以外の変更は必要ありません。

印刷データ作成（プリンター内蔵フォント）プログラム上の変更

レシート上の文字に使用されるプリンター内蔵フォント印刷は、以下サンプルのように変わります。実際には利用している機能に合わせて変更をお願いします。

対応している機能の一覧は ISCBBuilder をご確認ください。

注釈

TSP100シリーズはプリンターフォントに対応していません。 印刷データ作成（画像データ）プログラム上の変更 をご確認ください。

Before: starioだけを利用する

NSMutableData *commands = [NSMutableData new];

Byte initial[] = {0x1b, 0x40};                // Initialization
[commands appendBytes:initial length:2];
Byte alignment[] = {0x1b, 0x1d, 0x61, 0x01};  // Alignment
[commands appendBytes:alignment length:4];
[commands appendData:[@"Hello World" dataUsingEncoding:NSASCIIStringEncoding]];

Byte alignment[] = {0x1b, 0x64, 0x02};        // Cut paper

After: stario + ISCBBuilder/StarIO_Extensionを利用する

ISCBBuilder *builder = [StarIoExt createCommandBuilder:emulation];

[builder beginDocument];
[builder appendAlignment:SCBAlignmentPositionRight];
NSData *textData = [@"Hello World" dataUsingEncoding:NSASCIIStringEncoding];
[builder appendData:textData];
[builder appendCutPaper:SCBCutPaperActionPartialCutWithFeed];
[builder endDocument];

[builder.commands copy];

印刷データ作成（画像データ）プログラム上の変更

レシート上の店舗ロゴなどに使用される画像データ印刷は、以下サンプルのように変わります。実際には利用している機能に合わせて変更をお願いします。

対応している機能の一覧は ISCBBuilder をご確認ください。

After: stario + ISCBBuilder/StarIO_Extensionを利用する

ISCBBuilder *builder = [StarIoExt createCommandBuilder:emulation];

[builder beginDocument];
[builder appendBitmap:bitmap_image diffusion:YES];  // create Star command from bitmap data
[builder appendCutPaper:SCBCutPaperActionPartialCutWithFeed];
[builder endDocument];

[builder.commands copy];

6.1.4. プリンターモデルの追加方法

プリンターモデルの追加や移行をする場合でも、プリンターコマンドの生成に ISCBBuilder を利用しているのであれば、ほとんどのケースはエミュレーション指定の変更だけで完了します。

ただし、一部状況においては追加の変更が必要になるため、下記案内を参考に変更をお願いします。

Emulationの指定方法（ ISCBBuilder ）

mC-Print3とそれ以外のプリンターでは、搭載しているエミュレーションが異なることがあります。

StarIoExtEmulation のページで対応エミュレーションを確認し、 ISCBBuilder インスタンス生成時にエミュレーション指定を変更してください。

例として、TSP100/TSP650IIとmC-Print3では、下記表に沿ったエミュレーション指定の変更が必要です。

Printer	StarIoExtEmulation
TSP650II	StarIoExtEmulationStarLine
TSP100	StarIoExtEmulationStarGraphic
mC-Print3	StarIoExtEmulationStarPRNT

エミュレーション指定のサンプル

// TSP650II (StarLine)
// StarIoExtEmulation emulation = StarIoExtEmulationStarLine

// TSP100 (StarGraphic)
// StarIoExtEmulation emulation = StarIoExtEmulationStarGraphic

// mC-Print3 (StarPRNT)
StarIoExtEmulation emulation = StarIoExtEmulationStarPRNT
ISCBBuilder *builder = [StarIoExt createCommandBuilder:emulation];

searchPrinter の検索方法

searchPrinter によるプリンターの検索方法は同一です。

検索で得られるモデル名をアプリケーション内で何かしらの判別に利用している場合は、対応が必要になります。

例として、検索結果に含まれるプリンターモデル名は下記の通りです。

LANインターフェース

Printer	Model Name (PortInfo)
mC-Print2	"MCP21", "MCP20"
mC-Print3	"MCP31", "MCP30"
mC-Label3	"MCL32"
TSP100IV	"TSP143IV"
TSP100IV SK	"TSP143IV"
TSP100IIILAN	"TSP143IIILAN", "TSP143IIIW"
TSP650II	"TSP654"
TSP700II	"TSP743II"
TSP800II	"TSP847II"
SP700	"SP712", "SP742", "SP717", "SP747"

Bluetooth/Lightningインターフェース

Printer	Model Name (PortInfo)
mC-Print2	"MCP21LB"", "MCP20B", "MCP20L"
mC-Print3	"MCP31L", "MCP31LB", "MCP31CI", "MCP31CBI"
mC-Label3	"MCL32CI", "MCL32CBI"
mPOP	"POP10CBI", "POP10CI", "POP10 BLK", "POP10 WHT"
TSP100III	"TSP143IIIU WT", "TSP143IIIU GY", "TSP143IIIBI WT", "TSP143IIIBI GY"
TSP650II	"Star Micronics"
TSP700II	"Star Micronics"
TSP800II	"Star Micronics"
SP700	"Star Micronics"
SM-S210i	"SM-S210"[3], "SM-S210I"[4]
SM-S230i	"SM-S230"[3], "SM-S230I"[4]
SM-T300i	"SM-T300"[3], "SM-T300I"[4]
SM-T400i	"SM-T400"[3], "SM-T400I"[4]
SM-L200	"SM-L200"
SM-L300	"SM-L300"

[3]	ファームウェアバージョン5.0未満

[4]	ファームウェアバージョン5.0以降

getPort - portName引数の指定方法

Bluetooth/Lightningインターフェース

portName の指定に searchPrinter の戻り値（ PortInfo ）を利用している場合、引数の変更は必要ありません。

ただし、引数を直接設定（固定値など）している場合は、デバイス名の初期値がmC-Print3とそれ以外で異なるため、引数を変更しなければいけない可能性があります。

例として、TSP100/TSP650IIとmC-Print3の初期値は下記の通りです。

Printer	iOS Port Name
TSP100	"TSP100"
TSP650II	"Star Micronics"
mC-Print3	"mC-Print3"

portNameのサンプル

SMPort *port = nil;
NSString *portSettings = "";

// TSP650II (Bluetooth)
// NSString *portName = "BT:Star Micronics";

// TSP100 (Bluetooth)
// NSString *portName = "BT:TSP100";

// mC-Print3 (Bluetooth)
// NSString *portName = "BT:mC-Print3";

// No changes required if used "BT:"
NSString *portName = "BT:";

port = [SMPort getPort:portName :portSettings :(uint32_t) timeout :&error];

その他インターフェース

プリンター固有のデバイス名はありません。 getPort のページを参考に、インターフェースごと適切な portName を設定してください。

getPort - portSettings引数の指定方法

各プリンターモデルで適用すべき識別子が異なることがあります。 getPort のページ「2. portSettings 引数」を参考に変更してください。

例として、TSP100/TSP650IIとmC-Print3の portSettings は同一です。

Printer	portSettings
TSP100	""
TSP650II	""
mC-Print3	""

portSettingsのサンプル

SMPort port = nil;
NSString *portName = "BT:";

// NSString *portSettings = "l10000"
NSString *portSettings = "";

port = [SMPort getPort:portName :portSettings :(uint32_t) timeout :&error];

印字領域の指定方法

プリンターモデルの組み合わせによっては印字領域設定の初期値が異なります。必要に応じて appendPrintableArea で領域を指定してください。

appendBitmap などを用いてグラフィックデータを印刷している場合は、移行先プリンターモデルの印字領域に合わせてレイアウト変更をお願いします。

6.1.5. コマンド生成からデータ送信までのコード上の流れ

コマンド生成から書き込みまでの一連です。実際には下記関数を非UIスレッドで実行してください。

-(void) printSample {
    ISCBBuilder *builder = [StarIoExt createCommandBuilder:StarIoExtEmulationStarPRNT];

    [builder beginDocument];
    [builder appendData:[@"Hello World" dataUsingEncoding:NSASCIIStringEncoding]];
    [builder appendCutPaper:SCBCutPaperActionPartialCutWithFeed];
    [builder endDocument];

    Byte commands[] = [builder.commands copy];

    NSString *portName = "BT:";
    NSString *portSettings = "";

    SMPort *port = [SMPort getPort:portName :portSettings :10000 :&error];

    if (port == nil) {
        // ERROR
        code = error.code;
    }

    StarPrinterStatus_2 printerStatus;
    result = CommResultErrorBeginCheckedBlock;

    [port beginCheckedBlock:&printerStatus :2 :&error];

    if (error != nil) {
        // ERROR
        code = error.code;
    }

    uint32_t total = 0;

    while (total < (uint32_t) commands.length) {
        uint32_t written = [port writePort:(unsigned char *) commands.bytes :total :(uint32_t) commands.length - total :&error];

        if (error != nil) {
            // ERROR
            code = error.code;
        }

        total += written;
    }

    port.endCheckedBlockTimeoutMillis = 30000;

    result = CommResultErrorEndCheckedBlock;

    [port endCheckedBlock:&printerStatus :2 :&error];

    if (error != nil) {
        // ERROR
        code = error.code;
    }

    if (printerStatus.offline == SM_TRUE) {
        // OFFLINE
    }

    result = CommResultSuccess;
    code   = SMStarIOResultCodeSuccess;
}