Componentes y ejemplos

Esta sección documenta cada componente con su contrato y un ejemplo de uso tomado de la aplicación de demostración. Los ejemplos envuelven las llamadas AIDL en funciones suspend para simplificar el manejo de los callbacks.

Impresora (IPrinter)

La impresión es asíncrona y se basa en plantillas. No se imprime de forma programática elemento por elemento: se envía una plantilla en formato JSON (la estructura del documento) y un objeto de datos (los valores). El resultado llega por un listener.

Contrato

Estructura de la plantilla

La plantilla es un arreglo de "items". Cada item tiene una lista unit con elementos. Las variables se escriben como <nombre> en el campo data y se rellenan con el objeto de datos. Tipos de unidad soportados:

Ejemplo: Imprimir una boleta con logo, PDF417 y QR

Plantilla (resumida) con un logo, una fila de total y un PDF417:

[
  { "unit": [ { "type": "image", "data": "<logo>",
                "align": "center", "width": 160, "height": 160 } ] },
  { "unit": [ { "type": "text", "data": "<comercio>",
                "align": "center", "size": "FONT_BIG",
                "style": "TEXT_STYLE_BOLD" } ] },
  { "unit": [ { "type": "line", "data": "" } ] },
  { "unit": [ { "type": "row", "columns": [
      { "type": "text", "data": "TOTAL", "align": "left" },
      { "type": "text", "data": "<total>", "align": "right" } ] } ] },
  { "unit": [ { "type": "barcode", "data": "<pdf417_data>",
                "format": "PDF_417", "align": "center",
                "width": 360, "height": 120 } ] },
  { "unit": [ { "type": "qrcode", "data": "<qr_data>",
                "align": "center", "width": 240, "height": 240 } ] }
]

Datos que rellenan las variables:

{
  "logo": "<PNG en base64>",
  "comercio": "TIENDA DEMO BCI",
  "total": "$7.400",
  "pdf417_data": "BCI-DEMO|FOLIO:000123456|TOTAL:7400",
  "qr_data": "https://bci.cl/boleta/000123456"
}

Invocación con listener, envuelta en una función suspend:

suspend fun imprimir(template: String, data: String, key: String): Boolean =
  suspendCancellableCoroutine { cont ->
    val p = IPrinter.Stub.asInterface(
        bridge.getRawBinder(HalComponent.PRINTER))
    val listener = object : IPrinterListener.Stub() {
      override fun onStatusChanged(status: Int) {}
      override fun onPrintResult(resp: PrintWithTemplateResponse?) {
        val ok = (resp?.resultCode == -1)   // -1 = éxito
        if (cont.isActive) cont.resume(ok)
      }
    }
    p.registerListener(listener)
    val req = PrintWithTemplateRequest().apply {
      this.template = template; this.data = data
      this.msgVersion = ""; this.key = key
    }
    p.printWithTemplate(req)   // oneway: retorna de inmediato
  }

Cámara / Escáner (ICamera)

Permite escanear códigos (QR, PDF417, códigos de barras 1D y 2D) usando la cámara del terminal. En equipos PAX se utiliza el escáner nativo del SDK, que abre su propia pantalla de captura con mira y entrega el resultado por el listener.

Contrato (métodos principales)

Resultado del escaneo (ICameraListener)

• onScanSuccess(result): entrega el resultado con la lista de códigos leídos (cada uno con formato y texto). El formato indica el tipo de lectura (por ejemplo EAN13, QRCODE, PDF417).
• onTimeout(partial): venció el tiempo; puede traer resultados parciales.
• onError(code, msg): error durante el escaneo.

Ejemplo: escanear un código con el escáner nativo PAX

suspend fun escanearCamara(key: String, timeoutMs: Long): List<String> =
  suspendCancellableCoroutine { cont ->
    val cam = ICamera.Stub.asInterface(
        bridge.getRawBinder(HalComponent.CAMERA))
    val codigos = mutableListOf<String>()
    val listener = object : ICameraListener.Stub() {
      override fun onScanSuccess(r: CameraScannerResult?) {
        r?.barcodes?.forEach { codigos.add("${it.format}: ${it.text}") }
        try { cam.unregisterListener(this) } catch (_: Exception) {}
        cont.resume(codigos)
      }
      override fun onTimeout(r: CameraScannerResult?) {
        try { cam.unregisterListener(this) } catch (_: Exception) {}
        cont.resume(codigos)
      }
      override fun onError(c: Int, m: String?) {
        try { cam.unregisterListener(this) } catch (_: Exception) {}
        cont.resume(emptyList())
      }
      override fun onPictureTaken(path: String?) {}
      override fun onStatusUpdate(s: Int) {}
      override fun onScanAreaUpdate(l:Int,t:Int,r:Int,b:Int,w:Int,h:Int) {}
    }
    cam.registerListener(listener)
    // En PAX, sin surface: usa el escáner nativo (su propia pantalla).
    cam.scanCodes(key, 1, emptyList(), timeoutMs, false, listener)
  }

Lector de hardware dedicado (IScanner)

Algunos terminales incluyen un lector de hardware dedicado (infrarrojo/láser, típicamente accionado por un gatillo). Este componente lo expone de forma independiente de la cámara.

Ejemplo: lectura con el lector dedicado

suspend fun escanearHw(key: String, timeoutMs: Int): List<String> =
  suspendCancellableCoroutine { cont ->
    val sc = IScanner.Stub.asInterface(
        bridge.getRawBinder(HalComponent.SCANNER))
    val codigos = mutableListOf<String>()
    val listener = object : IScannerListener.Stub() {
      override fun onSuccess(result: String?) {
        if (!result.isNullOrEmpty()) codigos.add(result)
        try { sc.unregisterListener(this) } catch (_: Exception) {}
        cont.resume(codigos)
      }
      override fun onTimeout() {
        try { sc.unregisterListener(this) } catch (_: Exception) {}
        cont.resume(codigos)
      }
      override fun onError(c: Int, m: String?) {
        try { sc.unregisterListener(this) } catch (_: Exception) {}
        cont.resume(emptyList())
      }
    }
    val cfg = ScannerConfig().apply {
      continuousTimes = 1; timeout = timeoutMs
    }
    sc.config(key, cfg)
    sc.registerListener(listener)
    sc.scan(key, listener)
  }

Banda magnética (IMagneticStripe)

Lee los tracks de una tarjeta de banda magnética. El modelo correcto de uso es por eventos: se abre el lector, se registra un listener, y al deslizar la tarjeta llega el callback con los datos. El lector queda esperando el deslizamiento; no es una lectura instantánea.

Ejemplo: lectura por evento

suspend fun leerBanda(key: String): MagStripeTrackData? =
  suspendCancellableCoroutine { cont ->
    val m = IMagneticStripe.Stub.asInterface(
        bridge.getRawBinder(HalComponent.MAGSTRIPE))
    val listener = object : IMagStripeListener.Stub() {
      override fun onSwiped(data: MagStripeTrackData?) {
        cont.resume(data)
        m.close(key)
      }
      override fun onError(c: Int, msg: String?) { cont.resume(null) }
      override fun onOperationResult(op: Int, ok: Boolean, json: String?) {}
    }
    m.registerListener(listener)
    m.open(key, 1)   // abre con nivel de seguridad 1 (enmascarado) y queda esperando el deslizamiento
  }

Información del equipo (IDeviceInfo)

Entrega datos identificatorios del terminal. Es de solo lectura y síncrono.

val d = IDeviceInfo.Stub.asInterface(
    bridge.getRawBinder(HalComponent.DEVICEINFO))
val modelo = d.getModel(key)
val serie  = d.getSerialNumber(key)
val firmware = d.getFirmwareVersion(key)

Señal sonora (IBeep)

Reproduce señales sonoras de retroalimentación. Útil para confirmar éxito o error de una operación.

val beep = IBeep.Stub.asInterface(
    bridge.getRawBinder(HalComponent.BEEP))
beep.beepSuccess(key)   // tono de éxito
beep.beepError(key)     // tono de error

NFC (INfc)

Permite detectar y leer etiquetas/tarjetas sin contacto (UID, tecnología, e intercambio de comandos APDU). La detección y lectura están operativas.

Diagnóstico (IDiagnostic)

Expone métricas de uso de cada componente (número de llamadas, fallos, tiempos promedio). Pensado para herramientas administrativas y de monitoreo.