@rdlabo/capacitor-brotherprint 8.1.1 → 8.2.0

package/docs/print.md

@@ -0,0 +1,36 @@
+# Print
+
+`printImage` sends a base64 image (MIME type removed) to a Brother printer. Call this after [Installation](/docs/installation). Discover a printer with [Search](/docs/search) and register [Events](/docs/events) for print results before printing.
+
+Prepare a real image yourself (for example encode a PNG/JPEG from your app and strip any `data:...;base64,` prefix). Use `port` and `channelInfo` from the `BRLMChannelResult` you retained from `onPrinterAvailable`. Pick a `modelName` / `labelName` that matches your device and the [supported models](/docs/readme#supported-models) table.
+
+```typescript
+import {
+  BrotherPrint,
+  BRLMPrinterLabelName,
+  BRLMPrinterModelName,
+} from '@rdlabo/capacitor-brotherprint';
+import type { BRLMChannelResult, BRLMPrintOptions } from '@rdlabo/capacitor-brotherprint';
+
+const printImage = async (printer: BRLMChannelResult, encodedImage: string) => {
+  const options: BRLMPrintOptions = {
+    modelName: BRLMPrinterModelName.QL_820NWB,
+    labelName: BRLMPrinterLabelName.RollW62,
+    encodedImage,
+    numberOfCopies: 1,
+    autoCut: true,
+    port: printer.port,
+    channelInfo: printer.channelInfo,
+  };
+
+  await BrotherPrint.printImage(options);
+};
+```
+
+See the demo for a complete page:
+
+https://github.com/rdlabo-dev/capacitor-brotherprint/blob/v8.1.1/demo/src/app/home/home.page.ts
+
+<!-- !::printImage:: -->
+
+<!-- !::BRLMPrintOptions:: -->

package/docs/search.md

@@ -0,0 +1,106 @@
+# Search
+
+Search finds nearby Brother printers. Results arrive on `onPrinterAvailable`. Call this after [Installation](/docs/installation). Register the listener before `search`, keep the discovered `BRLMChannelResult` (especially `channelInfo` and `port`), then continue to [Print](/docs/print). Full event list: [Events](/docs/events).
+
+## search
+
+Register `onPrinterAvailable`, retain the channel, then start a Wi-Fi search. The `search` call itself returns `void`.
+
+```typescript
+import type { PluginListenerHandle } from '@capacitor/core';
+import {
+  BrotherPrint,
+  BrotherPrintEventsEnum,
+  BRLMPrinterPort,
+} from '@rdlabo/capacitor-brotherprint';
+import type { BRLMChannelResult } from '@rdlabo/capacitor-brotherprint';
+
+let discovered: BRLMChannelResult | undefined;
+let availableHandle: PluginListenerHandle | undefined;
+
+const searchWifiPrinters = async () => {
+  if (!availableHandle) {
+    availableHandle = await BrotherPrint.addListener(
+    BrotherPrintEventsEnum.onPrinterAvailable,
+    (printer) => {
+      discovered = printer;
+      console.log('channelInfo', printer.channelInfo);
+    },
+    );
+  }
+
+  await BrotherPrint.search({
+    port: BRLMPrinterPort.wifi,
+    searchDuration: 15, // seconds
+  });
+};
+
+const stopSearching = async () => {
+  try {
+    await BrotherPrint.cancelSearchWiFiPrinter();
+  } finally {
+    await availableHandle?.remove();
+    availableHandle = undefined;
+  }
+};
+```
+
+Call `searchWifiPrinters` from the search button and await `stopSearching` when leaving the screen.
+
+On iOS, `bluetooth` first lists connected MFi printers. If none are connected, the app displays the system Bluetooth accessory picker so you can select and pair a printer. The search promise completes after the picker callback; picker errors reject the promise.
+
+For BLE-capable printers, use `port: BRLMPrinterPort.bluetoothLowEnergy`. On iOS this uses `startBLESearch`, without the Bluetooth accessory picker. Pass the discovered printer's `channelInfo` (BLE local name) unchanged to `isChannelAvailable` or `printImage`. BLE search errors reject the search promise. QL-820NWB/QL-820NWBc do not support BLE printing; use `bluetooth` or `wifi` for these models.
+
+On Android, pair a Bluetooth printer in the system settings before calling `search` with `bluetooth`; the SDK lists paired printers and does not provide the iOS accessory picker. Bluetooth and BLE searches resolve after the search finishes, or reject on SDK errors. Android 12 and later request Nearby devices permissions; Android 11 and earlier request location permission for BLE. `isChannelAvailable` returns `false` when Bluetooth permission is missing.
+
+`searchDuration` applies to `wifi` and `bluetoothLowEnergy`. `usb` is Android only. If nothing is found, you get no error and no printers. Signatures are on the [API](/docs/api#brlmsearchoption) page.
+
+On Android, Bluetooth Classic searches return paired devices. To include only devices that report the Bluetooth Imaging/Printer class:
+
+```typescript
+await BrotherPrint.search({
+  port: BRLMPrinterPort.bluetooth,
+  searchDuration: 15,
+  bluetoothPrintersOnly: true,
+});
+```
+
+`bluetoothPrintersOnly` defaults to `false`, preserving the unfiltered results. It is ignored on iOS and for other ports, including BLE. The filter does not depend on device names and does not identify Brother products: other manufacturers' printers can still appear. Printers with a missing or non-printer Bluetooth class are excluded when enabled.
+
+## isChannelAvailable
+
+If you saved the last `BRLMChannelResult`, check whether that channel is still usable before [Print](/docs/print).
+
+```typescript
+import { BrotherPrint } from '@rdlabo/capacitor-brotherprint';
+import type { BRLMChannelResult } from '@rdlabo/capacitor-brotherprint';
+
+const checkChannel = async (lastPrinter: BRLMChannelResult) => {
+  const { result } = await BrotherPrint.isChannelAvailable(lastPrinter);
+  if (!result) {
+    await BrotherPrint.search({
+      port: lastPrinter.port,
+      searchDuration: 15,
+    });
+  }
+};
+```
+
+<!-- !::isChannelAvailable:: -->
+
+<!-- !::isChannelAvailableResult:: -->
+
+<!-- !::BRLMChannelResult:: -->
+
+## cancelSearchWiFiPrinter / cancelSearchBluetoothPrinter
+
+Use these to stop an active search before its timeout, including when leaving the screen.
+
+```typescript
+import { BrotherPrint } from '@rdlabo/capacitor-brotherprint';
+
+await BrotherPrint.cancelSearchWiFiPrinter();
+await BrotherPrint.cancelSearchBluetoothPrinter();
+```
+
+See [API](/docs/api#cancelsearchwifiprinter) for the cancellation signatures.

package/docs/usage.md

@@ -0,0 +1,76 @@
+# Usage
+
+The following Angular component shows how to set up listeners, search for printers, and print a base64-encoded image.
+
+```typescript
+@Component({
+  selector: 'brother-print',
+  templateUrl: 'brother.component.html',
+  styleUrls: ['brother.component.scss'],
+})
+export class BrotherComponent implements OnInit, OnDestroy {
+  readonly #listenerHandlers: PluginListenerHandle[] = [];
+  readonly printers = signal<BRLMChannelResult[]>([]);
+
+  async ngOnInit() {
+    this.#listenerHandlers.push(
+      await BrotherPrint.addListener(BrotherPrintEventsEnum.onPrint, () => {
+        console.log('onPrint');
+      }),
+    );
+    this.#listenerHandlers.push(
+      await BrotherPrint.addListener(BrotherPrintEventsEnum.onPrintError, (info) => {
+        console.log('onPrintError');
+      }),
+    );
+    this.#listenerHandlers.push(
+      await BrotherPrint.addListener(BrotherPrintEventsEnum.onPrintFailedCommunication, (info) => {
+        console.log('onPrintFailedCommunication');
+      }),
+    );
+    this.#listenerHandlers.push(
+      await BrotherPrint.addListener(BrotherPrintEventsEnum.onPrinterAvailable, (printer) => {
+        this.printers.update((prev) => [...prev, printer]);
+      }),
+    );
+  }
+
+  async ngOnDestroy() {
+    this.#listenerHandlers.forEach((handler) => handler.remove());
+  }
+
+  async searchPrinter(port: BRKMPrinterPort) {
+    // This method return void. Get the printer list by listening to the event.
+    await BrotherPrint.search({
+      port,
+      searchDuration: 15, // seconds
+    });
+  }
+
+  print() {
+    if (this.printers().length === 0) {
+      console.error('No printer found');
+      return;
+    }
+
+    const defaultPrintSettings: BRLMPrintOptions = {
+      modelName: BRLMPrinterModelName.QL_820NWB,
+      labelName: BRLMPrinterLabelName.RollW62,
+      encodedImage: 'base64 removed mime-type', // base64
+      numberOfCopies: 1, // default 1
+      autoCut: true, // default true
+    };
+
+    BrotherPrint.printImage({
+      ...defaultPrintSettings,
+      ...{
+        port: this.printers()[0].port,
+        channelInfo: this.printers()[0].channelInfo,
+      },
+    });
+  }
+}
+```
+
+See demo for complete code:
+https://github.com/rdlabo-dev/capacitor-brotherprint/blob/main/demo/src/app/home/home.page.ts

package/ios/Sources/BrotherPrintPlugin/BrotherPrintPlugin.swift

@@ -23,11 +23,16 @@ public class BrotherPrintPlugin: CAPPlugin, CAPBridgedPlugin {
     @objc func printImage(_ call: CAPPluginCall) {
         let encodedImage: String = call.getString("encodedImage", "")
         if encodedImage == "" {
+            self.notifyListeners(BrotherPrinterEvent.onPrintError.rawValue, data: ["code": 0, "message": "Error - Image data is not found."])
             call.reject("Error - Image data is not found.")
             return
         }
 
-        let newImageData = Data(base64Encoded: encodedImage, options: [])
+        guard let image = decodePrintImage(encodedImage) else {
+            self.notifyListeners(BrotherPrinterEvent.onPrintError.rawValue, data: ["code": 0, "message": "Error - Create decodedByte From ImageData is failed."])
+            call.reject("Error - Create decodedByte From ImageData is failed.")
+            return
+        }
 
         // 検索からデバイス情報が得られた場合
         let port: String = call.getString("port", "wifi")
@@ -54,6 +59,7 @@ public class BrotherPrintPlugin: CAPPlugin, CAPBridgedPlugin {
             case "bluetoothLowEnergy":
                 channel = BRLMChannel(bleLocalName: channelInfo)
             default:
+                self.notifyListeners(BrotherPrinterEvent.onPrintError.rawValue, data: ["code": 0, "message": "Error - connection is not found."])
                 call.reject("Error - connection is not found.")
                 return
             }
@@ -70,14 +76,6 @@ public class BrotherPrintPlugin: CAPPlugin, CAPBridgedPlugin {
                 return
             }
 
-            guard
-                let decodedByte = UIImage(data: newImageData! as Data)
-            else {
-                printerDriver.closeChannel()
-                call.reject("Error - Create decodedByte From ImageData is failed.")
-                return
-            }
-
             var printSettings: BRLMPrintSettingsProtocol
 
             if modelName.hasPrefix("QL") {
@@ -85,7 +83,7 @@ public class BrotherPrintPlugin: CAPPlugin, CAPBridgedPlugin {
                     let _printSettings = BRLMQLPrintSettings(defaultPrintSettingsWith: printerModel)
                 else {
                     printerDriver.closeChannel()
-                    self.notifyListeners(BrotherPrinterEvent.onPrintFailedCommunication.rawValue, data: [
+                    self.notifyListeners(BrotherPrinterEvent.onPrintError.rawValue, data: [
                         "code": 0,
                         "message": "Error - Create BRLMQLPrintSettings with " + modelName + " is failed."
                     ])
@@ -99,7 +97,7 @@ public class BrotherPrintPlugin: CAPPlugin, CAPBridgedPlugin {
                     let _printSettings = BRLMTDPrintSettings(defaultPrintSettingsWith: printerModel)
                 else {
                     printerDriver.closeChannel()
-                    self.notifyListeners(BrotherPrinterEvent.onPrintFailedCommunication.rawValue, data: [
+                    self.notifyListeners(BrotherPrinterEvent.onPrintError.rawValue, data: [
                         "code": 0,
                         "message": "Error - Create BRLMTDPrintSettings with " + modelName + " is failed."
                     ])
@@ -110,11 +108,12 @@ public class BrotherPrintPlugin: CAPPlugin, CAPBridgedPlugin {
 
             } else {
                 printerDriver.closeChannel()
+                self.notifyListeners(BrotherPrinterEvent.onPrintError.rawValue, data: ["code": 0, "message": "Error - " + modelName + " is not supported"])
                 call.reject("Error - " + modelName + " is not supported")
                 return
             }
 
-            let printError = printerDriver.printImage(with: decodedByte.cgImage!, settings: printSettings)
+            let printError = printerDriver.printImage(with: image, settings: printSettings)
 
             if printError.code != BRLMPrintErrorCode.noError {
                 printerDriver.closeChannel()
@@ -209,6 +208,21 @@ public class BrotherPrintPlugin: CAPPlugin, CAPBridgedPlugin {
                 call.reject("Error - startBluetoothSearch: " + PrinterSearchErrorModel.fetchChannelErrorCode(error: searcher.error.code))
                 return
             }
+            if searcher.channels.isEmpty {
+                DispatchQueue.main.async {
+                    BRLMPrinterSearcher.startBluetoothAccessorySearch { result in
+                        guard result.error.code == BRLMPrinterSearchErrorCode.noError else {
+                            call.reject("Error - startBluetoothAccessorySearch: " + PrinterSearchErrorModel.fetchChannelErrorCode(error: result.error.code))
+                            return
+                        }
+                        for channel in result.channels {
+                            self.notifyListeners(BrotherPrinterEvent.onPrinterAvailable.rawValue, data: self.chanelToPrinter(port: "bluetooth", channel: channel))
+                        }
+                        call.resolve()
+                    }
+                }
+                return
+            }
             for channel in searcher.channels {
                 NSLog(channel.channelInfo)
                 self.notifyListeners(BrotherPrinterEvent.onPrinterAvailable.rawValue, data: self.chanelToPrinter(port: "bluetooth", channel: channel))
@@ -216,12 +230,6 @@ public class BrotherPrintPlugin: CAPPlugin, CAPBridgedPlugin {
             call.resolve()
         }
 
-        //        BRLMPrinterSearcher.startBluetoothAccessorySearch() { searcher in
-        //            for channel in searcher.channels {
-        //                self.notifyListeners(BrotherPrinterEvent.onPrinterAvailable.rawValue, data: self.chanelToPrinter(port: "bluetooth", channel: channel))
-        //            }
-        //            call.resolve()
-        //        }
     }
 
     private func searchBLEPrinter(_ call: CAPPluginCall) {
@@ -229,13 +237,17 @@ public class BrotherPrintPlugin: CAPPlugin, CAPBridgedPlugin {
             self.cancelRoutineBluetooth = {
                 BRLMPrinterSearcher.cancelBLESearch()
             }
+            defer { self.cancelRoutineBluetooth = nil }
             let option = BRLMBLESearchOption()
             option.searchDuration = TimeInterval(call.getInt("searchDuration", 15))
             NSLog("BRLMPrinterSearcher.startBLESearch")
-            BRLMPrinterSearcher.startBLESearch(option) { channel in
+            let searcher = BRLMPrinterSearcher.startBLESearch(option) { channel in
                 self.notifyListeners(BrotherPrinterEvent.onPrinterAvailable.rawValue, data: self.chanelToPrinter(port: "bluetoothLowEnergy", channel: channel))
             }
-            self.cancelRoutineBluetooth = nil
+            guard searcher.error.code == BRLMPrinterSearchErrorCode.noError else {
+                call.reject("Error - startBLESearch: " + PrinterSearchErrorModel.fetchChannelErrorCode(error: searcher.error.code))
+                return
+            }
             call.resolve()
         }
     }
@@ -263,6 +275,7 @@ public class BrotherPrintPlugin: CAPPlugin, CAPBridgedPlugin {
         DispatchQueue.global().async {
             self.cancelRoutineWiFi?()
             self.cancelRoutineWiFi = nil
+            call.resolve()
         }
     }
 
@@ -270,6 +283,7 @@ public class BrotherPrintPlugin: CAPPlugin, CAPBridgedPlugin {
         DispatchQueue.global().async {
             self.cancelRoutineBluetooth?()
             self.cancelRoutineBluetooth = nil
+            call.resolve()
         }
     }
 }

package/ios/Sources/BrotherPrintPlugin/Info.plist

@@ -33,6 +33,8 @@
         <string>_ipp._tcp</string>
     </array>
     <key>UISupportedExternalAccessoryProtocols</key>
-    <string>com.brother.ptcbp</string>
+    <array>
+        <string>com.brother.ptcbp</string>
+    </array>
 </dict>
 </plist>

package/ios/Sources/BrotherPrintPlugin/PrintImageDecoder.swift

@@ -0,0 +1,9 @@
+import UIKit
+
+func decodePrintImage(_ encodedImage: String) -> CGImage? {
+    guard let data = Data(base64Encoded: encodedImage, options: []),
+          let image = UIImage(data: data) else {
+        return nil
+    }
+    return image.cgImage
+}

package/ios/Tests/BrotherPrintPluginTests/BrotherPrintPluginTests.swift

@@ -1,15 +1,36 @@
 import XCTest
+import Capacitor
 @testable import BrotherPrintPlugin
 
-class ExampleTests: XCTestCase {
-    func testEcho() {
-        // This is an example of a functional test case for a plugin.
-        // Use XCTAssert and related functions to verify your tests produce the correct results.
-
-        let implementation = BrotherPrintPlugin()
-        let value = "Hello, World!"
-        let result = implementation.echo(value)
-
-        XCTAssertEqual(value, result)
+class PrintImageValidationTests: XCTestCase {
+    func testInvalidImagesRejectBeforeOpeningPrinter() {
+        for image in ["", "A", "SGVsbG8=", "iVBORw0KGgo="] {
+            var rejected = 0
+            var errorEvents = 0
+            var errorMessage: String?
+            let plugin = BrotherPrintPlugin()
+            // Normally initialized by Capacitor when attaching the bridge.
+            plugin.eventListeners = NSMutableDictionary()
+            for eventName in ["onPrintError", "onPrint", "onPrintFailedCommunication"] {
+                let listener = CAPPluginCall(callbackId: eventName, methodName: "addListener", options: ["eventName": eventName], success: { result, _ in
+                    XCTAssertEqual(eventName, "onPrintError")
+                    XCTAssertEqual(result?.data?["code"] as? Int, 0)
+                    errorMessage = result?.data?["message"] as? String
+                    errorEvents += 1
+                }, error: { _ in
+                    XCTFail("Listener must not reject")
+                })!
+                plugin.addListener(listener)
+            }
+            let call = CAPPluginCall(callbackId: "test", methodName: "printImage", options: ["encodedImage": image], success: { _, _ in
+                XCTFail("Invalid image must not resolve")
+            }, error: { error in
+                XCTAssertEqual(errorMessage, error?.message)
+                rejected += 1
+            })!
+            plugin.printImage(call)
+            XCTAssertEqual(rejected, 1, "Input: \(image)")
+            XCTAssertEqual(errorEvents, 1, "Input: \(image)")
+        }
     }
 }

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@rdlabo/capacitor-brotherprint",
-  "version": "8.1.1",
+  "private": false,
+  "version": "8.2.0",
   "description": "Capacitor plugin for Brother Print SDK",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",
@@ -68,6 +69,7 @@
     "android/src/main/",
     "android/build.gradle",
     "dist/",
+    "docs/",
     "ios/Sources",
     "ios/Tests",
     "Package.swift",
@@ -93,9 +95,10 @@
   },
   "repository": {
     "type": "git",
-    "url": "git@github.com:rdlabo-team/capacitor-brotherprint.git"
+    "url": "git@github.com:rdlabo-dev/capacitor-brotherprint.git"
   },
   "bugs": {
-    "url": "git@github.com:rdlabo-team/capacitor-brotherprint.git/issues"
-  }
+    "url": "git@github.com:rdlabo-dev/capacitor-brotherprint.git/issues"
+  },
+  "homepage": "https://docs.rdlabo.dev/projects/capacitor-brotherprint"
 }