Referência de interfaces de serviço

Esta página cataloga todas as interfaces AIDL que sua Manufacturer Service App pode implementar. Também lista os valores fixos que a plataforma da Getnet espera de algumas delas. Para as chamadas que exercitam essas interfaces, consulte Implementar os serviços de hardware.

IMainService

O ponto de entrada. A Middleware App se vincula ao seu serviço pelo pacote com.pagonxt.hal.platform.service e obtém um stub IMainService. Por esse stub ela alcança todas as demais interfaces.

Método de acesso	Devolve
`getStats()`	`IStatService`
`getPrinter()`	`IPrinterService`
`getCard()`	`ICardService`
`getMifare()`	`IMifareService`
`getBeeper()`	`IBeeperService`
`getLed()`	`ILedService`
`getInfo()`	`IInfoService`
`getCamera()`	`ICameraService`
`getEmv()`	`IEMVInterface`

ICardService

Cuida da busca de cartão em todas as tecnologias de leitura que seu dispositivo suporta.

Método	Descrição
`search(long timeout, in String[] searchType, in ICardCallback callback)`	Busca um cartão usando um ou mais dos tipos de busca abaixo, até `timeout` se esgotar.
`stopAllReaders()`	Para todos os leitores ativos. Chame assim que `onCard`, `onMessage` ou `onError` disparar.

Tipos de busca:

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

onCard devolve um CardResponse com pan (chip e NFC) ou track1 / track2 / track3 (tarja magnética).

IMifareService

Cobre presença de cartão Mifare, autenticação e leitura/escrita em nível de bloco.

Método	Descrição
`searchCard(in IMifareCallback callback)`	Busca um cartão Mifare.
`searchCardAndActivate(in IMifareActivateCallback callback)`	Busca e ativa um cartão Mifare em uma só chamada.
`activate(int cardType)`	Ativa um cartão do tipo indicado.
`halt()`	Para o cartão ativo.
`getCardSerialNo(int cardType)`	Devolve o número de série (UID) do cartão como string hexadecimal.
`authenticateSectorWithKeyA(int sector, in byte[] key)`	Autentica um setor com a Key A.
`authenticateBlockWithKeyA(int sector, in byte[] key)`	Autentica um bloco com a Key A.
`authenticateSectorWithKeyB(int block, in byte[] key)`	Autentica um setor com a Key B.
`authenticateBlockWithKeyB(int block, in byte[] key)`	Autentica um bloco com a Key B.
`close()`	Fecha a sessão Mifare atual.
`decrement(int index, int value)`	Decrementa em `value` o bloco de valor em `index`.
`increment(int index, int value)`	Incrementa em `value` o bloco de valor em `index`.
`isExist()`	Devolve se há um cartão Mifare presente.
`readBlock(int index)`	Lê o bloco em `index`, devolvido como string.
`restore(int index)`	Restaura o bloco de valor em `index`.
`transfer(int index)`	Transfere o bloco de valor em `index`.
`writeBlock(int index, String data)`	Escreve `data` no bloco em `index`.
`exchangeAPDU(in byte[] apdu)`	Envia um APDU bruto e devolve um `APDUResponse`.

As chaves têm 6 bytes. A autenticação de bloco e de setor usa os nomes de parâmetro como declarados no AIDL acima. authenticateBlockWithKeyA/B recebem um parâmetro literalmente chamado sector, embora ele identifique um bloco.

IPrinterService

Monta e imprime um recibo a partir de uma fila de elementos de texto, código de barras, código QR e imagem.

Método	Descrição
`init()`	Inicializa a impressora. Todo outro método lança `IllegalStateException` se for chamado antes deste.
`getStatus()`	Devolve o status atual da impressora.
`setGray(int gray)`	Define o nível de escala de cinza aplicado às imagens.
`addText(int align, String text)`	Enfileira uma linha de texto com o alinhamento indicado.
`addBarCode(int align, String barcode)`	Enfileira um código de barras.
`addQrCode(int align, int imageHeight, String qrCode)`	Enfileira um código QR com a altura indicada.
`addImageBitmap(int align, in Bitmap bitmap)`	Enfileira uma imagem `Bitmap`.
`addImageByteArray(int align, in byte[] byteArray)`	Enfileira uma imagem a partir de bytes brutos.
`defineFontFormat(int fontFormat)`	Define a fonte ativa.
`print(in IPrinterCallback callback)`	Imprime tudo o que está enfileirado.
`printAndRemovePaper(in IPrinterCallback callback)`	Imprime tudo o que está enfileirado e depois avança e corta o papel.

Constantes de fonte

defineFontFormat recebe uma destas três constantes.

Constante	Valor	Tamanho
`FONT_12_16A`	`11`	Pequeno
`FONT_16_32B`	`15`	Médio
`FONT_32_32B`	`22`	Grande

Especificações da impressora

Valores e comportamentos fixos que sua implementação de impressora deve seguir.

Regra	Valor
Tamanho máximo de imagem	378 pixels. Seu serviço redimensiona automaticamente imagens maiores.
Máximo de caracteres por linha — fontes média e grande	32 caracteres. Média e grande só diferem na altura.
Máximo de caracteres por linha — fonte pequena	48 caracteres.
Limiar de escala de cinza	175. Seu serviço é responsável pela transformação em escala de cinza.
Chamadas repetidas a `init()`	Não devem limpar a fila de impressão. Limpe-a apenas quando o método `print()` do seu serviço rodar.
Métodos de imagem	Todos os métodos `addImage*` devem aceitar entrada `Bitmap`.
Texto longo	Chamadas a `addText` que ultrapassem o limite de caracteres devem quebrar automaticamente em várias linhas.
Nova linha após conteúdo enfileirado	Todo método que enfileira conteúdo (texto ou imagem) deve acrescentar automaticamente uma quebra de linha.

IBeeperService

Toca retorno sonoro para as ações do portador e do operador.

Método	Descrição
`custom(int durationMillis)`	Toca um bipe pela duração indicada, em milissegundos.

Sons nomeados e sua duração exigida:

Som	Duração
`success`	Bipe de 500 ms.
`error`	Bipe de 1000 ms.
`digit`	Bipe de 100 ms.
`nfc`	Bipe de 100 ms, pausa de 300 ms, bipe de 100 ms.

ILedService

Um par liga/desliga por cor: turnOnRed / turnOffRed, turnOnBlue / turnOffBlue, turnOnYellow / turnOffYellow, turnOnGreen / turnOffGreen.

IInfoService

Devolve os dados de identificação do dispositivo. Consulte InfoResponse para a lista completa de campos.

ICameraService

Lê a câmera frontal do dispositivo para casos de uso de escaneamento.

Método	Descrição
`readFront(long timeout, in ICameraCallback callback)`	Lê a câmera frontal até `timeout` se esgotar, ou até quem chamou cancelar a leitura.

O ICameraCallback reporta por onSuccess(code), onTimeout(), onCancel() e onError(error).

IStatService

Reporta as contagens de uso de leituras de cartão e de consumo de papel, tanto no dispositivo inteiro quanto por aplicação chamadora.

Método	Descrição
`getPaperStatus()`	Consumo total de papel, no dispositivo inteiro.
`getAllAppPaperStatus()`	Consumo de papel, por aplicação chamadora.
`getMagStatus()`	Total de leituras de tarja magnética bem-sucedidas.
`getAllAppMagStatus()`	Leituras de tarja magnética bem-sucedidas, por aplicação.
`getMagStatusFail()`	Total de falhas de tarja magnética.
`getAllAppMagStatusFail()`	Falhas de tarja magnética, por aplicação.
`getChipStatus()`	Total de inserções de chip bem-sucedidas.
`getAllAppChipStatus()`	Inserções de chip bem-sucedidas, por aplicação.
`getChipStatusFail()`	Total de falhas de inserção de chip.
`getAllAppChipStatusFail()`	Falhas de inserção de chip, por aplicação.
`getNfcStatus()`	Total de transações contactless (NFC) bem-sucedidas.
`getAllAppNfcStatus()`	Transações contactless bem-sucedidas, por aplicação.
`getNfcStatusFail()`	Total de falhas contactless.
`getAllAppNfcStatusFail()`	Falhas contactless, por aplicação.
`getMifareStatus()`	Total de leituras de proximidade Mifare bem-sucedidas.
`getMifareStatusFail()`	Total de falhas de proximidade Mifare.
`getAllStatisticsByApp()`	Todas as contagens de sucesso e falha acima, agrupadas por aplicação.

Vários métodos HAL recebem um parâmetro userId que identifica a aplicação chamadora. Exemplos incluem print(int userId, IPrinterCallback callback) e searchMag(int userId, long timeout, in ICardCallback callback). Resolva userId para um nome de pacote com packageManager.getNameForUid(userId) para atribuir as estatísticas corretamente.

IEMVInterface

Usada por IMainService::getEmv. Consulte Máquina de estados EMV para ver como esses métodos se encaixam em uma transação.

Método	Descrição
`create(IEMVEventsAIDL events)`	Associa um listener de eventos ao serviço. Chame antes de qualquer transação.
`reset()`	Reinicia todos os parâmetros de longo prazo.
`version()`	Devolve uma `List<Version>` descrevendo o kernel EMV em execução.
`setAIDParameter(in List<AIDParameter> data)`	Define os parâmetros específicos de AID. De longo prazo, prioridade alta exceto para os parâmetros definidos por `setTLV`.
`setCAKey(in List<CAKey> data)`	Define a lista de chaves da autoridade certificadora. De longo prazo, prioridade baixa.
`setRevoked(in List<Revoked> data)`	Define a lista de números de série de certificado revogados. De longo prazo.
`setRiskManagement(in Risk risk)`	Define os parâmetros de gestão de risco da transação. De longo prazo.
`setTLV(in List<TLV> tlvs)`	Define uma lista de TLVs apenas para a transação atual. De curto prazo, prioridade máxima.
`setTerminal(in Terminal terminal)`	Define os dados do terminal. De longo prazo, sobrescreve parâmetros definidos anteriormente.
`start(in List<String> aidList, in Transaction transaction)`	Inicia a coleta de dados do cartão para uma transação. O kernel EMV ignora qualquer AID que não esteja presente em `setAIDParameter`.
`get(in List<String> list, IGetCallback get)`	Recupera os TLVs solicitados de forma assíncrona.
`getSimplified(in List<String> data)`	Recupera os TLVs solicitados de forma síncrona, devolvidos como `List<TLV>`.
`cancel()`	Cancela o fluxo EMV atual. A aplicação ainda precisa aguardar o evento de fim antes de dar a transação por cancelada.

IMaintenanceInterface

Cobre a manutenção do dispositivo: autoverificações, atualizações remotas e ajustes de relógio.

Método	Descrição
`setSelfTestHourRange(String min, String max)`	Define a janela de reinício por autoverificação (auto-reset), como strings `"HH:mm"`. Devolve `0` em caso de sucesso, `-1` em caso de erro.
`setAutoUpdateHourRange(String min, String max)`	Define a janela de tentativa de atualização automática, como strings `"HH:mm"`. Devolve `0` em caso de sucesso, `-1` em caso de erro.
`setAutoUpdate(boolean isEnabled, boolean autoRebootEnabled)`	Ativa ou desativa a atualização automática. Devolve `0` em caso de sucesso, `-1` em caso de erro.
`setAllowGprsUpdate(boolean isEnabled)`	Permite ou bloqueia a atualização remota por 3G/4G. Devolve `0` em caso de sucesso, `-1` em caso de erro.
`installApp(String filePath, IMaintenanceResult result)`	Instala o APK em `filePath` em segundo plano (sem interação do usuário). Devolve `0` em caso de sucesso, `-1` em caso de erro.
`uninstallApp(String packageName, IMaintenanceResult result)`	Desinstala `packageName` em segundo plano (sem interação do usuário). Devolve `0` em caso de sucesso, `-1` em caso de erro.
`setTimeZone(String id)`	Define o fuso horário do dispositivo. Devolve `0` em caso de sucesso, `-1` em caso de erro.
`setDateTime(String dateTime)`	Define a data e hora local do dispositivo, como `"YYYYMMDDHHmmss"` (por exemplo, `"20250314093500"`). Devolve `0` em caso de sucesso, `-1` em caso de erro.

IEncryptionInterface

Cobre o status das chaves e a criptografia de dados para a gestão de chaves do dispositivo.

Método	Descrição
`getKSNbyPosition(int index)`	Devolve o KSN codificado em hexadecimal da chave em `index`, ou uma string vazia se não existir.
`injectWorkingKey(int index, int mkIndex, in byte[] keyBlock)`	Injeta uma chave de trabalho em `index`, criptografada pela chave mestra em `mkIndex`.
`encryptData(int index, int method, in byte[] plainText)`	Criptografa `plainText` com a chave em `index`. `method` é `1` para modo CBC ou `2` para modo EBC, conforme documenta o kit do fabricante. Devolve os dados criptografados, ou `null` em caso de erro.

InfoResponse

Campos devolvidos por IInfoService e pelas chamadas de informação de dispositivo relacionadas:

Campo	Descrição
`sdkVersion`	Versão do SDK instalado.
`bcVersion`	Versão do componente de boot/base.
`osVersion`	Versão do sistema operacional.
`serialNumber`	Número de série do dispositivo.
`psamId`	Identificador PSAM.
`model`	Modelo do dispositivo.
`manufacture`	Fabricante do dispositivo.
`imsi`	IMSI do SIM, se presente.
`imei`	IMEI do dispositivo.
`iccid`	ICCID do SIM, se presente.
`romVersion`	Versão da ROM.
`androidKernelVersion`	Versão do kernel Android.
`androidOSVersion`	Versão do sistema operacional Android.
`hardwareVersion`	Revisão de hardware.
`firmwareVersion`	Versão do firmware.
`hardWareSn`	Número de série de hardware.

Recursos relacionados

Arquitetura HAL — como essas interfaces se encaixam.
Implementar os serviços de hardware — as chamadas que exercitam a maioria das interfaces acima.
Máquina de estados EMV — o fluxo construído sobre IEMVInterface.