SCMEnvironment

public final class SCMEnvironment

Main class for the Smart Card Middleware API.

This class provides the initial entry points for connecting to the iOS API, obtaining the readers and listening to events.

  • Call this from your applicationDidEnterBackground(_ application: UIApplication).

    Declaration

    Swift

    public static func notifyApplicationDidEnterBackground()

  • Call this from your applicationWillTerminate(_ application: UIApplication).

    Declaration

    Swift

    public func notifyApplicationWillTerminate()

  • Initializes the list of all smart card readers attached to the device (through getReaders()) and starts monitoring smart card reader events.

    Example:

    var environment: SCMEnvironment? = nil;
group = DispatchGroup()
group.enter()
DispatchQueue.global(qos: .background).async {
    SCMEnvironment.createEnvironment { env, error in
        if let error = error {
        // fail to create the environment
        }
        else {
            environment = env
        }
        group.leave()
    }
}
group.wait()
if let env = environment {
   env.addReaderListener(listener: self);
}

    Note:

    If the device supports NFC Tag Reading, a NFC Reader named "NFC Interface" will be added to getReaders() array.

    Declaration

    Swift

    public static func createEnvironment(completionHandler: @escaping (_ env: SCMEnvironment?, _ error: NSError?) -> Void)

    Parameters

    completionHandler

    The completion handler block to be called as soon as the environment is created. It takes the following parameters:

    • env SCMEnvironment?: the newly created SCMEnvironment object.
    • error : nil if the environment creation is completed successfully; otherwise an error encapsulates the reason of failure.

    Note

    The completion handler is executed on the same type of DispatchQueue as in the calling code.

Reader

  • Returns the list of all smart card readers attached to the device.

    Declaration

    Swift

    public func getReaders() -> Array<Reader>

    Return Value

    an Array of Reader objects detected by the devices.

  • Gets the Reader object with the given name.

    Declaration

    Swift

    public func getReader(readerName: String) -> Reader?

    Parameters

    readerName

    The reader name.

    Return Value

    The Reader object.

  • Registers a reader event listener.

    See also

    ReaderEvents

    Declaration

    Swift

    public func addReaderListener(listener: ReaderEvents)

    Parameters

    listener

    The listener instance whose methods will be called when an event occurs.

  • Removes a reader event listener.

    See also

    ReaderEvents

    Declaration

    Swift

    public func removeReaderEventListener(listener: ReaderEvents)

    Parameters

    listener

    The listener instance to remove.

Bluetooth

  • Returns an array of the bluetooth peripherals visible to the device.

    Example:

    do {
    let peripherals = try env.getDetectedBluetoothPeripherals();
}
catch SCMError.CXR_BT_INITIALIZATION_FAILED {
    // handle failed initialization of bluetooth
}
catch SCMError.CXR_BT_NOT_SCANNING {
    // start scan
}
catch SCMError.CXR_BT_ALREADY_PAIRED {
    // you can't use this function while being connected
}
catch {
        // other error
}

    See also

    BluetoothPeripheral, SCMError

    Throws

    A SCMError representing the occuring error.

    Declaration

    Swift

    public func getDetectedBluetoothPeripherals() throws -> Array<BluetoothPeripheral>

    Return Value

    An array of BluetoothPeripheral objects.

  • Registers a bluetooth peripheral.

    See also

    SeeAlso:SCMError

    Throws

    A SCMError representing the occuring error.

    Declaration

    Swift

    public func registerBluetooth(uuid: String, _ override: Bool = false) throws

    Parameters

    uuid

    The Universally Unique Identifier of the bluetooth peripheral.

  • Returns the registered bluetooth peripheral.

    See also

    BluetoothPeripheral.

    Declaration

    Swift

    public func getRegisteredBluetooth() -> BluetoothPeripheral?

    Return Value

    A BluetoothPeripheral object representing the paired bluetooth device. nil if there are no paired bluetooth device.

  • Starts the scan for bluetooth devices.

    See also

    SCMError.

    Throws

    A SCMError representing the occuring error.

    Declaration

    Swift

    public func startBluetoothScan() throws -> Bool

    Return Value

    true if scan could be started, false if a scan is already started.

  • Gets if a bluetooth scan is running, for detecting bluetooth peripherals.

    Declaration

    Swift

    public func isScanningBluetooth() -> Bool

    Return Value

    true if a scan is currently running.

  • Stops scan for bluetooth peripherals.

    See also

    SCMError.

    Throws

    A SCMError representing the occuring error.

    Declaration

    Swift

    public func stopBluetoothScan() throws -> Bool

    Return Value

    true if scan is stopped, false if it was already stopped.

  • Disconnects the current bluetooth peripheral

    See also

    SCMError.

    Throws

    A SCMError representing the occuring error.

    Declaration

    Swift

    public func releaseBluetooth() throws -> Bool

    Return Value

    wether or not disconecting from the peripheral was successful.

  • Unregisters the paired bluetooth. This function also disconnects the current connected device.

    Declaration

    Swift

    public func unregisterBluetooth()

NFC

  • Starts scanning for NFC tags. After calling this function, iOS will display an alert action sheet waiting to detect tags.

    Example:

    env.initTagReaderSession(message: "Present your smart card to the phone") { error in
    if let error = error {
        if error.scmError == SCMError.CXR_FUNCTION_TIMED_OUT {
            // the session has timed out
        }
        else if error.scmError == SCMError.CKR_FUNCTION_CANCELED {
            // the session was canceled by the user
        }
        else {
            // other failure reason
        }
    }
    else {
        // the session ended with a call to endTagReaderSession(errorMessage:String?)
    }
)

    Declaration

    Swift

    @available(iOS 13.0, *)
public func initTagReaderSession(message: String?, completionHandler: @escaping (_ error: NSError?) -> Void)

    Parameters

    message

    Descriptive text message that is displayed on the alert action sheet once tag scanning has started. The string can be updated dynamically by calling SCMEnvironment.updateTagReaderSession(message:).
    completionHandler

    The completion handler block to be called when the session ends. If the operation has been ended explicitly by a SCMEnvironment.endTagReaderSession(message:) call. The Completion handler is called from background thread. It takes the following parameter:

    • error NSError?: nil if the session ended without any error. If session was canceled by user or timed out the localizedDescription of the error contains more information.

  • Closes the NFC Tag reader session and displays a feedback to the user.

    Note:

    If the session was not successful, a message must be provided, which will be displayed to the user as an error. If the operation was successful, the message must be set to nil. In this case, a positive check mark will be displayed to the user.

    Declaration

    Swift

    @available(iOS 13.0, *)
public func endTagReaderSession(errorMessage: String?)

    Parameters

    errorMessage

    nil if the session was successful, or a message error to display otherwise.

  • Updates the text message that was displayed on the alert action sheet of the NFC Tag Reader Session.

    Declaration

    Swift

    @available(iOS 13.0, *)
public func updateTagReaderSession(message: String)

    Parameters

    message

    the new text message to be displayed on the alert action sheet.

  • Returns if the device supports NFC Tag Reading.

    Declaration

    Swift

    @available(iOS 13.0, *)
public func isSupportedNfcTagReaderSession() -> Bool

    Return Value

    true if the device supports NFC Tag Reader Session; false otherwise.