feat!: Hint input parameter and Format output parameter (#31)

* feat!: Support hint parameter in scanning

References: https://outsystemsrd.atlassian.net/browse/RMET-2962

BREAKING CHANGE: This adds a new parameter to `scanBarcode` in `OSBARCManagerProtocol`, which is a breaking change

* refactor!: Extract scan parameters to structure

References: https://outsystemsrd.atlassian.net/browse/RMET-2962

BREAKING CHANGE: This modifies the signature of the public `scanBarcode`, but allows for easier addition of new parameters to avoid future breaking changes.

* feat!: return scanned text and format

References: https://outsystemsrd.atlassian.net/browse/RMET-2962

BREAKING CHANGE: This modifies the output of the public `scanBarcode`, but allows for easier addition of new output to avoid future breaking changes.

* chore(ci): Use macos-14 instead of macos-latest

Because macos-14 comes with more Xcode versions.

To be addressed in https://outsystemsrd.atlassian.net/browse/RMET-4424

* chore(ci): Remove specific device requirement from unit tests

* chore(ci): fix Fastfile

* chore: fix unit tests

* chore: revert formatting

* docs: Update README and CHANGELOG

References: https://outsystemsrd.atlassian.net/browse/RMET-2962

Author: OS-pedrogustavobilro

.github/workflows/github_actions.yml

@@ -7,7 +7,7 @@ on:
 jobs:    
   test:
     name: Unit-Tests
-    runs-on: macos-latest
+    runs-on: macos-14
     steps:
     - name: Checkout
       uses: actions/checkout@v4

.github/workflows/prepare_release.yml

@@ -16,7 +16,7 @@ on:
 jobs:
   build-and-release:
     if: github.ref == 'refs/heads/main'
-    runs-on: macos-latest
+    runs-on: macos-14
     steps:
       - name: Checkout
         uses: actions/checkout@v4

.github/workflows/release_and_publish.yml

@@ -9,7 +9,7 @@ on:
 jobs:
   post-merge:
     if: contains(github.event.pull_request.labels.*.name, 'release') && github.event.pull_request.merged == true
-    runs-on: macos-latest
+    runs-on: macos-14
 
     steps:
     - name: Checkout Repository

.gitignore

@@ -91,4 +91,5 @@ iOSInjectionProject/
 .swiftlint.yml
 
 scripts/build/
-.DS_Store
+build/
+.DS_Store

CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+**BREAKING CHANGE**: The signature of `scanBarcode` has been updated, both input and output.
+
+- Add **hint** parameter to scan for specific barcode formats
+- Return the format of the scanned code inside the scan result.
+
 ## 1.1.3
 - Increase scanning area (https://outsystemsrd.atlassian.net/browse/RMET-3683).
 

OSBarcodeLib.xcodeproj/project.pbxproj

@@ -7,6 +7,10 @@
 	objects = {
 
 /* Begin PBXBuildFile section */
+		630812572E5866D900536FE7 /* OSBARCScannerHint.swift in Sources */ = {isa = PBXBuildFile; fileRef = 630812562E5866C700536FE7 /* OSBARCScannerHint.swift */; };
+		6308125D2E58902B00536FE7 /* OSBARCScannerHint+VNBarcodeSymbology.swift in Sources */ = {isa = PBXBuildFile; fileRef = 6308125C2E58902100536FE7 /* OSBARCScannerHint+VNBarcodeSymbology.swift */; };
+		6308125F2E5891ED00536FE7 /* OSBARCScanParameters.swift in Sources */ = {isa = PBXBuildFile; fileRef = 6308125E2E5891E700536FE7 /* OSBARCScanParameters.swift */; };
+		630812612E589F5A00536FE7 /* OSBARCScanResult.swift in Sources */ = {isa = PBXBuildFile; fileRef = 630812602E589F5600536FE7 /* OSBARCScanResult.swift */; };
 		7507FC1B27FC2AAE003809F6 /* OSBarcodeLib.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 7507FC1227FC2AAE003809F6 /* OSBarcodeLib.framework */; };
 		750B35872AFA93B100F90083 /* OSBARCScannerViewConfigurationValues.swift in Sources */ = {isa = PBXBuildFile; fileRef = 750B35862AFA93B100F90083 /* OSBARCScannerViewConfigurationValues.swift */; };
 		7513C4852B03E86B005E81C4 /* OSBARCDeviceTypeModel.swift in Sources */ = {isa = PBXBuildFile; fileRef = 7513C4802B03E86B005E81C4 /* OSBARCDeviceTypeModel.swift */; };
@@ -70,6 +74,10 @@
 /* End PBXContainerItemProxy section */
 
 /* Begin PBXFileReference section */
+		630812562E5866C700536FE7 /* OSBARCScannerHint.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = OSBARCScannerHint.swift; sourceTree = "<group>"; };
+		6308125C2E58902100536FE7 /* OSBARCScannerHint+VNBarcodeSymbology.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "OSBARCScannerHint+VNBarcodeSymbology.swift"; sourceTree = "<group>"; };
+		6308125E2E5891E700536FE7 /* OSBARCScanParameters.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = OSBARCScanParameters.swift; sourceTree = "<group>"; };
+		630812602E589F5600536FE7 /* OSBARCScanResult.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = OSBARCScanResult.swift; sourceTree = "<group>"; };
 		7507FC1227FC2AAE003809F6 /* OSBarcodeLib.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; includeInIndex = 0; path = OSBarcodeLib.framework; sourceTree = BUILT_PRODUCTS_DIR; };
 		7507FC1A27FC2AAE003809F6 /* OSBarcodeLibTests.xctest */ = {isa = PBXFileReference; explicitFileType = wrapper.cfbundle; includeInIndex = 0; path = OSBarcodeLibTests.xctest; sourceTree = BUILT_PRODUCTS_DIR; };
 		750B35862AFA93B100F90083 /* OSBARCScannerViewConfigurationValues.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = OSBARCScannerViewConfigurationValues.swift; sourceTree = "<group>"; };
@@ -208,17 +216,21 @@
 		758E6C142B0238F100FC16D9 /* Models */ = {
 			isa = PBXGroup;
 			children = (
+				6308125E2E5891E700536FE7 /* OSBARCScanParameters.swift */,
 				7513C4822B03E86B005E81C4 /* MappableProtocol */,
 				758E6C152B0238FF00FC16D9 /* OSBARCCameraModel.swift */,
 				7513C4802B03E86B005E81C4 /* OSBARCDeviceTypeModel.swift */,
 				7513C4812B03E86B005E81C4 /* OSBARCOrientationModel.swift */,
+				630812562E5866C700536FE7 /* OSBARCScannerHint.swift */,
+				630812602E589F5600536FE7 /* OSBARCScanResult.swift */,
 			);
 			path = Models;
 			sourceTree = "<group>";
 		};
 		758E6C172B0239C100FC16D9 /* Extensions */ = {
 			isa = PBXGroup;
 			children = (
+				6308125C2E58902100536FE7 /* OSBARCScannerHint+VNBarcodeSymbology.swift */,
 				758E6C182B0239E700FC16D9 /* AVCaptureDevice+OSBARCModelMappable.swift */,
 				7513C48F2B03E922005E81C4 /* AVCaptureVideoOrientation+CustomInit.swift */,
 				75183A152B7389EC00AFC687 /* Float+DecimalPlacesCleaner.swift */,
@@ -436,6 +448,7 @@
 			buildActionMask = 2147483647;
 			files = (
 				75D20FEB2AF17C8E009AD84D /* OSBARCPermissionsBehaviour.swift in Sources */,
+				630812572E5866D900536FE7 /* OSBARCScannerHint.swift in Sources */,
 				750B35872AFA93B100F90083 /* OSBARCScannerViewConfigurationValues.swift in Sources */,
 				75183A162B7389EC00AFC687 /* Float+DecimalPlacesCleaner.swift in Sources */,
 				756E17452B754B6400D594DA /* OSBARCCameraManager.swift in Sources */,
@@ -453,6 +466,7 @@
 				75562B3F2B1767C100F31AF6 /* UIApplication+Window.swift in Sources */,
 				75D20FE72AF17AFC009AD84D /* OSBARCCoordinatorProtocol.swift in Sources */,
 				75D20FE22AF16B0A009AD84D /* OSBARCManagerFactory.swift in Sources */,
+				630812612E589F5A00536FE7 /* OSBARCScanResult.swift in Sources */,
 				75EF59A42B0E4A410084F144 /* OSBARCScanButton.swift in Sources */,
 				75183A182B73936500AFC687 /* OSBARCZoomSelectorView.swift in Sources */,
 				75D20FDC2AF16AC9009AD84D /* OSBARCManager.swift in Sources */,
@@ -474,7 +488,9 @@
 				755AB5882B768425006B6507 /* OSBARCCaptureOutputDecoder.swift in Sources */,
 				7513C4872B03E86B005E81C4 /* OSBARCDeviceTypeModelMappable.swift in Sources */,
 				75EF59A02B0E44660084F144 /* OSBARCInstructionsText.swift in Sources */,
+				6308125F2E5891ED00536FE7 /* OSBARCScanParameters.swift in Sources */,
 				7513C4882B03E86B005E81C4 /* OSBARCModelMappable.swift in Sources */,
+				6308125D2E58902B00536FE7 /* OSBARCScannerHint+VNBarcodeSymbology.swift in Sources */,
 				7513C4862B03E86B005E81C4 /* OSBARCOrientationModel.swift in Sources */,
 				75EF599A2B0E2F220084F144 /* OSBARCBackgroundView.swift in Sources */,
 				7513C4852B03E86B005E81C4 /* OSBARCDeviceTypeModel.swift in Sources */,

OSBarcodeLib/Manager/OSBARCManager.swift

@@ -33,34 +33,25 @@ struct OSBARCManager {
 
 /// Implementation of the `OSBARCManagerProtocol` methods.
 extension OSBARCManager: OSBARCManagerProtocol {
-    func scanBarcode(with instructionsText: String, _ buttonText: String?, _ cameraModel: OSBARCCameraModel, and orientationModel: OSBARCOrientationModel) async throws -> String {
+    func scanBarcode(with parameters: OSBARCScanParameters) async throws -> OSBARCScanResult {
         // validates if the user has access to the device's camera.
         let hasCameraAccess = await self.permissionsBehaviour.hasCameraAccess()
         if !hasCameraAccess { throw OSBARCManagerError.cameraAccessDenied }
         // requests the scanner to start, treating its result value.
         return try await withCheckedThrowingContinuation {
-            self.startScanning(with: instructionsText, buttonText, cameraModel, and: orientationModel, continuation: $0)
+            self.startScanning(with: parameters, continuation: $0)
         }
     }
 
     /// Triggers the scanner view.
     /// - Parameters:
-    ///   - instructionsText: Text to be displayed on the scanner view.
-    ///   - buttonText: Text to be displayed for the scan button, if this is configured. `Nil` value means that the button will not be shown.
-    ///   - cameraModel: Camera to use for input gathering.
-    ///   - orientationModel: Scanner view's orientation.
+    ///   - parameters: The full parameter list to configure the scanner
     ///   - continuation: Object responsible for returning the method's result to its caller.
-    private func startScanning(
-        with instructionsText: String,
-        _ buttonText: String?,
-        _ cameraModel: OSBARCCameraModel,
-        and orientationModel: OSBARCOrientationModel,
-        continuation: CheckedContinuation<String, any Error>
-    ) {
+    private func startScanning(with parameters: OSBARCScanParameters, continuation: CheckedContinuation<OSBARCScanResult, any Error>) {
         DispatchQueue.main.async {
-            self.scannerBehaviour.startScanning(with: instructionsText, buttonText, cameraModel, and: orientationModel) { scannedCode in
-                if !scannedCode.isEmpty {
-                    continuation.resume(returning: scannedCode)
+            self.scannerBehaviour.startScanning(with: parameters) { scanResult in
+                if !scanResult.text.isEmpty {
+                    continuation.resume(returning: scanResult)
                 } else {
                     continuation.resume(throwing: OSBARCManagerError.scanningCancelled)
                 }

OSBarcodeLib/Manager/OSBARCManagerProtocol.swift

@@ -5,10 +5,7 @@ public protocol OSBARCManagerProtocol {
     ///     `cameraAccessDenied`: If camera access has not been given.
     ///     `scanningCancelled`: If scanning has been cancelled.
     /// - Parameters:
-    ///   - instructionsText: Text to be displayed on the scanner view.
-    ///   - buttonText: Text to be displayed for the scan button, if this is configured. `Nil` value means that the button will not be shown.
-    ///   - cameraModel: Camera to use for input gathering.
-    ///   - orientationModel: Scanner view's orientation.
+    ///   - parameters: The full parameter list to configure the scanner
     /// - Returns: When successful, it returns the text associated with the scanned barcode.
-    func scanBarcode(with instructionsText: String, _ buttonText: String?, _ cameraModel: OSBARCCameraModel, and orientationModel: OSBARCOrientationModel) async throws -> String
+    func scanBarcode(with parameters: OSBARCScanParameters) async throws -> OSBARCScanResult
 }

OSBarcodeLib/Models/OSBARCScanParameters.swift

@@ -0,0 +1,28 @@
+public struct OSBARCScanParameters {
+    /// Text to be displayed on the scanner view.
+    public let scanInstructions: String
+    
+    /// Text to be displayed for the scan button, if this is configured. `Nil` value means that the button will not be shown.
+    public let scanButtonText: String?
+    
+    // Camera to use for input gathering.
+    public let cameraDirection: OSBARCCameraModel
+    
+    // Scanner view's orientation.
+    public let scanOrientation: OSBARCOrientationModel
+    
+    // The optional hint, to scan a specific format (e.g. only qr code). `Nil` or `unknown` value means it can scan all.
+    public let hint: OSBARCScannerHint?
+    
+    public init(scanInstructions: String,
+                scanButtonText: String?,
+                cameraDirection: OSBARCCameraModel,
+                scanOrientation: OSBARCOrientationModel,
+                hint: OSBARCScannerHint?) {
+        self.scanInstructions = scanInstructions
+        self.scanButtonText = scanButtonText
+        self.cameraDirection = cameraDirection
+        self.scanOrientation = scanOrientation
+        self.hint = hint
+    }
+}

OSBarcodeLib/Models/OSBARCScanResult.swift

@@ -0,0 +1,13 @@
+public struct OSBARCScanResult: Equatable {
+    /// The actual textual data that was scanned
+    public let text: String
+    
+    /// The format that was scanned, or `unknown` if unable to determine
+    public let format: OSBARCScannerHint
+}
+
+extension OSBARCScanResult {
+    static func empty() -> OSBARCScanResult {
+        return OSBARCScanResult(text: "", format: .unknown)
+    }
+}