Referencia de interfaces de servicio

Esta página cataloga todas las interfaces AIDL que tu Manufacturer Service App puede implementar. También enumera los valores fijos que la plataforma de Getnet espera de algunas de ellas. Para las llamadas que ejercitan estas interfaces, consulta Implementar los servicios de hardware.

IMainService

El punto de entrada. La Middleware App se vincula a tu servicio mediante el paquete com.pagonxt.hal.platform.service y obtiene un stub IMainService. A través de ese stub alcanza todas las demás interfaces.

Accesor	Devuelve
`getStats()`	`IStatService`
`getPrinter()`	`IPrinterService`
`getCard()`	`ICardService`
`getMifare()`	`IMifareService`
`getBeeper()`	`IBeeperService`
`getLed()`	`ILedService`
`getInfo()`	`IInfoService`
`getCamera()`	`ICameraService`
`getEmv()`	`IEMVInterface`

ICardService

Gestiona la búsqueda de tarjeta en todas las tecnologías de lectura que tu dispositivo soporte.

Método	Descripción
`search(long timeout, in String[] searchType, in ICardCallback callback)`	Busca una tarjeta usando uno o más de los tipos de búsqueda de abajo, hasta que transcurra `timeout`.
`stopAllReaders()`	Detiene todos los lectores activos. Llámalo en cuanto se dispare `onCard`, `onMessage` u `onError`.

Tipos de búsqueda:

Constante	Valor
`MAG`	`"1"`
`CHIP`	`"2"`
`NFC`	`"3"`

onCard devuelve un CardResponse con pan (chip y NFC) o track1 / track2 / track3 (banda magnética).

IMifareService

Cubre la presencia de tarjeta Mifare, la autenticación y la lectura/escritura a nivel de bloque.

Método	Descripción
`searchCard(in IMifareCallback callback)`	Busca una tarjeta Mifare.
`searchCardAndActivate(in IMifareActivateCallback callback)`	Busca y activa una tarjeta Mifare en una sola llamada.
`activate(int cardType)`	Activa una tarjeta del tipo indicado.
`halt()`	Detiene la tarjeta activa.
`getCardSerialNo(int cardType)`	Devuelve el número de serie (UID) de la tarjeta como cadena hexadecimal.
`authenticateSectorWithKeyA(int sector, in byte[] key)`	Autentica un sector con la Key A.
`authenticateBlockWithKeyA(int sector, in byte[] key)`	Autentica un bloque con la Key A.
`authenticateSectorWithKeyB(int block, in byte[] key)`	Autentica un sector con la Key B.
`authenticateBlockWithKeyB(int block, in byte[] key)`	Autentica un bloque con la Key B.
`close()`	Cierra la sesión Mifare actual.
`decrement(int index, int value)`	Decrementa en `value` el bloque de valor en `index`.
`increment(int index, int value)`	Incrementa en `value` el bloque de valor en `index`.
`isExist()`	Devuelve si hay una tarjeta Mifare presente.
`readBlock(int index)`	Lee el bloque en `index`, devuelto como cadena.
`restore(int index)`	Restaura el bloque de valor en `index`.
`transfer(int index)`	Transfiere el bloque de valor en `index`.
`writeBlock(int index, String data)`	Escribe `data` en el bloque en `index`.
`exchangeAPDU(in byte[] apdu)`	Envía un APDU en bruto y devuelve un `APDUResponse`.

Las claves son de 6 bytes. La autenticación de bloque y de sector usa los nombres de parámetro tal como están declarados en el AIDL de arriba. authenticateBlockWithKeyA/B reciben un parámetro literalmente llamado sector, aunque identifique un bloque.

IPrinterService

Construye e imprime un recibo a partir de una cola de elementos de texto, código de barras, código QR e imagen.

Método	Descripción
`init()`	Inicializa la impresora. Todos los demás métodos lanzan `IllegalStateException` si se llaman antes que este.
`getStatus()`	Devuelve el estado actual de la impresora.
`setGray(int gray)`	Fija el nivel de escala de grises aplicado a las imágenes.
`addText(int align, String text)`	Encola una línea de texto con la alineación indicada.
`addBarCode(int align, String barcode)`	Encola un código de barras.
`addQrCode(int align, int imageHeight, String qrCode)`	Encola un código QR con la altura indicada.
`addImageBitmap(int align, in Bitmap bitmap)`	Encola una imagen `Bitmap`.
`addImageByteArray(int align, in byte[] byteArray)`	Encola una imagen a partir de bytes en bruto.
`defineFontFormat(int fontFormat)`	Fija la fuente activa.
`print(in IPrinterCallback callback)`	Imprime todo lo encolado.
`printAndRemovePaper(in IPrinterCallback callback)`	Imprime todo lo encolado y después avanza y corta el papel.

Constantes de fuente

defineFontFormat toma una de estas tres constantes.

Constante	Valor	Tamaño
`FONT_12_16A`	`11`	Pequeño
`FONT_16_32B`	`15`	Mediano
`FONT_32_32B`	`22`	Grande

Especificaciones de la impresora

Valores y comportamientos fijos que tu implementación de impresora debe respetar.

Regla	Valor
Tamaño máximo de imagen	378 píxeles. Tu servicio redimensiona automáticamente las imágenes mayores.
Máximo de caracteres por línea — fuentes mediana y grande	32 caracteres. Mediana y grande solo se diferencian en la altura.
Máximo de caracteres por línea — fuente pequeña	48 caracteres.
Umbral de escala de grises	175. Tu servicio es responsable de la transformación a escala de grises.
Llamadas repetidas a `init()`	No deben vaciar la cola de impresión. Vacíala solo cuando se ejecute el método `print()` de tu servicio.
Métodos de imagen	Todos los métodos `addImage*` deben aceptar entrada `Bitmap`.
Texto largo	Las llamadas a `addText` que superen el límite de caracteres deben ajustarse automáticamente en varias líneas.
Salto de línea tras contenido encolado	Todo método que encola contenido (texto o imagen) debe añadir automáticamente un salto de línea.

IBeeperService

Reproduce retroalimentación sonora para las acciones del titular y del operador.

Método	Descripción
`custom(int durationMillis)`	Reproduce un pitido durante la duración indicada, en milisegundos.

Sonidos con nombre y su duración requerida:

Sonido	Duración
`success`	Pitido de 500 ms.
`error`	Pitido de 1000 ms.
`digit`	Pitido de 100 ms.
`nfc`	Pitido de 100 ms, pausa de 300 ms, pitido de 100 ms.

ILedService

Un par encendido/apagado por color: turnOnRed / turnOffRed, turnOnBlue / turnOffBlue, turnOnYellow / turnOffYellow, turnOnGreen / turnOffGreen.

IInfoService

Devuelve los datos de identificación del dispositivo. Consulta InfoResponse para la lista completa de campos.

ICameraService

Lee la cámara frontal del dispositivo para casos de uso de escaneo.

Método	Descripción
`readFront(long timeout, in ICameraCallback callback)`	Lee la cámara frontal hasta que transcurra `timeout`, o hasta que quien llama cancele la lectura.

ICameraCallback informa mediante onSuccess(code), onTimeout(), onCancel() y onError(error).

IStatService

Informa de los recuentos de uso de lecturas de tarjeta y de consumo de papel, tanto a nivel de dispositivo como por aplicación llamante.

Método	Descripción
`getPaperStatus()`	Consumo total de papel, a nivel de dispositivo.
`getAllAppPaperStatus()`	Consumo de papel, por aplicación llamante.
`getMagStatus()`	Total de lecturas de banda magnética con éxito.
`getAllAppMagStatus()`	Lecturas de banda magnética con éxito, por aplicación.
`getMagStatusFail()`	Total de fallos de banda magnética.
`getAllAppMagStatusFail()`	Fallos de banda magnética, por aplicación.
`getChipStatus()`	Total de inserciones de chip con éxito.
`getAllAppChipStatus()`	Inserciones de chip con éxito, por aplicación.
`getChipStatusFail()`	Total de fallos de inserción de chip.
`getAllAppChipStatusFail()`	Fallos de inserción de chip, por aplicación.
`getNfcStatus()`	Total de transacciones contactless (NFC) con éxito.
`getAllAppNfcStatus()`	Transacciones contactless con éxito, por aplicación.
`getNfcStatusFail()`	Total de fallos contactless.
`getAllAppNfcStatusFail()`	Fallos contactless, por aplicación.
`getMifareStatus()`	Total de lecturas de proximidad Mifare con éxito.
`getMifareStatusFail()`	Total de fallos de proximidad Mifare.
`getAllStatisticsByApp()`	Todos los recuentos de éxito y fallo anteriores, agrupados por aplicación.

Varios métodos HAL reciben un parámetro userId que identifica a la aplicación llamante. Algunos ejemplos son print(int userId, IPrinterCallback callback) y searchMag(int userId, long timeout, in ICardCallback callback). Resuelve userId a un nombre de paquete con packageManager.getNameForUid(userId) para atribuir las estadísticas correctamente.

IEMVInterface

Se usa a través de IMainService::getEmv. Consulta Máquina de estados EMV para ver cómo encajan estos métodos en una transacción.

Método	Descripción
`create(IEMVEventsAIDL events)`	Asocia un listener de eventos al servicio. Llámalo antes de cualquier transacción.
`reset()`	Reinicia todos los parámetros de largo plazo.
`version()`	Devuelve una `List<Version>` que describe el kernel EMV en ejecución.
`setAIDParameter(in List<AIDParameter> data)`	Fija los parámetros específicos de AID. De largo plazo, prioridad alta salvo para los parámetros fijados mediante `setTLV`.
`setCAKey(in List<CAKey> data)`	Fija la lista de claves de la autoridad de certificación. De largo plazo, prioridad baja.
`setRevoked(in List<Revoked> data)`	Fija la lista de números de serie de certificado revocados. De largo plazo.
`setRiskManagement(in Risk risk)`	Fija los parámetros de gestión de riesgo de la transacción. De largo plazo.
`setTLV(in List<TLV> tlvs)`	Fija una lista de TLV solo para la transacción actual. De corto plazo, prioridad máxima.
`setTerminal(in Terminal terminal)`	Fija los datos del terminal. De largo plazo, sobrescribe los parámetros fijados anteriormente.
`start(in List<String> aidList, in Transaction transaction)`	Inicia la recogida de datos de tarjeta para una transacción. El kernel EMV ignora cualquier AID que no esté presente en `setAIDParameter`.
`get(in List<String> list, IGetCallback get)`	Recupera los TLV solicitados de forma asíncrona.
`getSimplified(in List<String> data)`	Recupera los TLV solicitados de forma síncrona, devueltos como `List<TLV>`.
`cancel()`	Cancela el flujo EMV actual. La aplicación debe esperar igualmente el evento de fin antes de dar la transacción por cancelada.

IMaintenanceInterface

Cubre el mantenimiento del dispositivo: autocomprobaciones, actualizaciones remotas y ajustes de reloj.

Método	Descripción
`setSelfTestHourRange(String min, String max)`	Fija la ventana de reinicio por autocomprobación (auto-reset), como cadenas `"HH:mm"`. Devuelve `0` si tiene éxito, `-1` si hay error.
`setAutoUpdateHourRange(String min, String max)`	Fija la ventana de intento de actualización automática, como cadenas `"HH:mm"`. Devuelve `0` si tiene éxito, `-1` si hay error.
`setAutoUpdate(boolean isEnabled, boolean autoRebootEnabled)`	Activa o desactiva la actualización automática. Devuelve `0` si tiene éxito, `-1` si hay error.
`setAllowGprsUpdate(boolean isEnabled)`	Permite o bloquea la actualización remota por 3G/4G. Devuelve `0` si tiene éxito, `-1` si hay error.
`installApp(String filePath, IMaintenanceResult result)`	Instala el APK en `filePath` en segundo plano (sin intervención del usuario). Devuelve `0` si tiene éxito, `-1` si hay error.
`uninstallApp(String packageName, IMaintenanceResult result)`	Desinstala `packageName` en segundo plano (sin intervención del usuario). Devuelve `0` si tiene éxito, `-1` si hay error.
`setTimeZone(String id)`	Fija la zona horaria del dispositivo. Devuelve `0` si tiene éxito, `-1` si hay error.
`setDateTime(String dateTime)`	Fija la fecha y hora local del dispositivo, como `"YYYYMMDDHHmmss"` (por ejemplo, `"20250314093500"`). Devuelve `0` si tiene éxito, `-1` si hay error.

IEncryptionInterface

Cubre el estado de las claves y el cifrado de datos para la gestión de claves del dispositivo.

Método	Descripción
`getKSNbyPosition(int index)`	Devuelve el KSN codificado en hexadecimal de la clave en `index`, o una cadena vacía si no existe.
`injectWorkingKey(int index, int mkIndex, in byte[] keyBlock)`	Inyecta una clave de trabajo en `index`, cifrada por la clave maestra en `mkIndex`.
`encryptData(int index, int method, in byte[] plainText)`	Cifra `plainText` con la clave en `index`. `method` es `1` para modo CBC o `2` para modo EBC, según documenta el kit del fabricante. Devuelve los datos cifrados, o `null` si hay error.

InfoResponse

Campos devueltos por IInfoService y las llamadas de información de dispositivo relacionadas:

Campo	Descripción
`sdkVersion`	Versión del SDK instalado.
`bcVersion`	Versión del componente de arranque/base.
`osVersion`	Versión del sistema operativo.
`serialNumber`	Número de serie del dispositivo.
`psamId`	Identificador PSAM.
`model`	Modelo del dispositivo.
`manufacture`	Fabricante del dispositivo.
`imsi`	IMSI de la SIM, si está presente.
`imei`	IMEI del dispositivo.
`iccid`	ICCID de la SIM, si está presente.
`romVersion`	Versión de la ROM.
`androidKernelVersion`	Versión del kernel de Android.
`androidOSVersion`	Versión del sistema operativo Android.
`hardwareVersion`	Revisión de hardware.
`firmwareVersion`	Versión del firmware.
`hardWareSn`	Número de serie de hardware.

Recursos relacionados

Arquitectura HAL — cómo encajan entre sí estas interfaces.
Implementar los servicios de hardware — las llamadas que ejercitan la mayoría de las interfaces anteriores.
Máquina de estados EMV — el flujo construido sobre IEMVInterface.