Introdução à API

331 Pages·2011·1.5 MB·Portuguese

id37677408 pdfMachine by Broadgun Software - a great PDF writer! - a great PDF creator! - http://www.pdfmachine.com http://www.broadgun.com
Especifica(cid:231)ªo de API
Introdu(cid:231)ªo (cid:224) API
Esta documenta(cid:231)ªo apresenta aos fornecedores de equipamentos ATM, as defini(cid:231)ıes de API
(Application Program Interface), necessÆrias para execu(cid:231)ªo do software aplicativo ATM, desenvolvido
pelo BANCO DO BRASIL.
Em anexo, para referŒncia, seguem:
 listagem dos arquivos contendo as defini(cid:231)ıes de variÆveis e prot(cid:243)tipos de fun(cid:231)ıes (arquivos
include *.H);
 listagem dos arquivos de defini(cid:231)ªo (arquivos *.DEF)
O Banco se reserva no direito de efetuar altera(cid:231)ıes nas fun(cid:231)ıes definidas, sem (cid:244)nus
adicionais, durante o processo de homologa(cid:231)ªo do hardware e das API(cid:146)s, para adequar as
caracter(cid:237)sticas de hardware do equipamento adquirido (cid:224)s necessidades da aplica(cid:231)ªo, com o
objetivo de manter o atendimento dos requisitos do neg(cid:243)cio, de funcionalidade e de seguran(cid:231)a
da solu(cid:231)ªo.
PÆgina 1 de 331
Especifica(cid:231)ªo de API
Disposi(cid:231)ıes Gerais
1. Os fontes das API(cid:146)s definidas neste documento, bem como os fontes de todos os programas
necessÆrios ao correto funcionamento da API e do respectivo dispositivo (drivers, API, lib, demais
bibliotecas compilÆveis, etc), deverªo, obrigatoriamente, ser entregues ao Banco do Brasil, que
passam a ser propriedade do Banco para uso exclusivo em seus terminais.
2. As fun(cid:231)ıes definidas neste documento deverªo ser implementadas pelos fornecedores dos
equipamentos para os seguintes sistemas operacionais/distribui(cid:231)ıes (e entregues nesta ordem de
prioridade):
 LINUX compat(cid:237)vel com GNU/Linux SuSE Linux Enterprise Server (SLES) 11 SP1 32 e 64 bits,
HedHat Enterprise Desktop 5, e versıes superiores atØ a data de publica(cid:231)ªo do Edital.
 MS-Windows 7 Professional, em formato de m(cid:243)dulos de liga(cid:231)ªo din(cid:226)mica (DLL) 32 e 64 bits,
e versıes superiores atØ a data de publica(cid:231)ªo do Edital.
3. Nenhuma fun(cid:231)ªo da API poderÆ travar, sempre deverÆ passar algum retorno para a aplica(cid:231)ªo do
Banco, de modo a evitar o travamento desta.
4. Os Diagramas de Estado ou Diagrama de Funcionamento sªo meramente exemplificativos e define o
modo pelo qual o software do Banco deverÆ, a princ(cid:237)pio, utilizar as fun(cid:231)ıes da API.
5. As fun(cid:231)ıes de inicializa(cid:231)ªo (INITIALIZE) e de finaliza(cid:231)ªo (TERMINATE), poderªo ser chamadas a
partir de qualquer estado, e neste caso, o estado do dispositivo deverÆ ser reiniciado ou finalizado,
conforme o caso.
6. Quando o dispositivo possuir LED sinalizador, as fun(cid:231)ıes deverªo tratar as a(cid:231)ıes sobre este
indicador sempre que o Diagrama de Estado da unidade o definir.
7. No caso de sa(cid:237)da anormal (quebra) da aplica(cid:231)ªo, o comando initialize, deverÆ estar preparado para
reativar o dispositivo f(cid:237)sico novamente (iniciando-o).
8. (cid:201) obrigat(cid:243)ria a aderŒncia ao padrªo LSB 2.0 ou superior (Linux Standard Base) para
desenvolvimento das API(cid:146)s e drivers, salvo expressa autoriza(cid:231)ªo do Banco do Brasil.
9. O diret(cid:243)rio em que as bibliotecas estarªo localizados Ø definido pelo Banco, configurado no arquivo
/etc/ld.so.conf, cuja altera(cid:231)ªo Ø efetuada somente pelo Banco do Brasil. Para carregar uma biblioteca
informe somente seu nome como par(cid:226)mentro. Exemplo: para (cid:147)libbbxaio.nn.so(cid:148), informe (cid:147)bbxaio.nn(cid:148),
o loader vai encontrar a biblioteca correspondende e carregÆ-la. Arquivos de configura(cid:231)ªo e demais
arquivos do fornecedor deverªo estar em /home/term/base.
10. Para a versªo Linux, os nomes das bibliotecas deverªo seguir a forma libbbxmmm.so, onde mmm
representa as trŒs letras identificadoras do m(cid:243)dulo, por exemplo para a leitora de cartıes (CRW) a
biblioteca gerada terÆ a forma libbbxcrw.so
11. Deverªo ser gerados arquivos de log de eventos (erros/notifica(cid:231)ıes) contendo as ocorrŒncias
verificadas no acesso aos dispositivos existentes no terminal. Deverªo conter os dados necessÆrios
para a correta identifica(cid:231)ªo dos erros, de forma a auxiliar o tØcnico de hardware ou pessoal de
desenvolvimento da API na rÆpida identifica(cid:231)ªo de eventual problema. Os arquivos de log deverªo
estar localizados no subdiret(cid:243)rio base\log no caso do OS/2 e Windows ou (cid:147)/home/term/base/log(cid:148)
no caso do Linux e deverªo seguir a seguinte nomenclatura: bbxnnndd.log, onde nnn Ø o nome da
API e dd Ø o dia do mŒs. Exemplo: bbxcrw15.log Ø o log gerado pela API BBXCRW no dia 15.
12. No momento do Initialize, se jÆ existir arquivo de log para o dia corrente (dia+mŒs+ano), as
ocorrŒncias devem ser anexadas ao arquivo; senªo, deve sobrescrever o arquivo de log existente,
criando um novo. Por exemplo, se no Initialize do dia 15.11.2000 jÆ existir no disco r(cid:237)gido o arquivo
bbxcrw15.log com data de 15.11.2000, os pr(cid:243)ximos registros devem ser anexados (append) no
arquivo. Se, por outro lado, o arquivo bbxcrw15.log existente no disco r(cid:237)gido tiver data diferente de
15.11.2000, o arquivo deve ser sobrescrito. Dessa maneira, o log de cada API fica dispon(cid:237)vel no
disco r(cid:237)gido por 1 mŒs.
PÆgina 2 de 331
Especifica(cid:231)ªo de API
13. Para o Banco, um mesmo fornecedor deverÆ manter sempre uma œnica API para um mesmo
dispositivo (independente da diversidade de firmware/hardware que poderÆ vir a existir). Ou com a
implementa(cid:231)ªo de uma API (cid:147)WRAPER(cid:148) para que a compatibilidade seja mantida, neste caso,
atravØs da implementa(cid:231)ªo de diversas APIs BBX para atender cada versªo de firmware/hardware, as
quais deverªo ser carregadas de acordo com a configura(cid:231)ªo do hardware. No entanto tal carga
deverÆ ser transparente para o software do Banco que sempre chamarÆ as fun(cid:231)ıes descritas nesta
documenta(cid:231)ªo.
14. Durante a execu(cid:231)ªo de uma fun(cid:231)ªo, o mecanismo deverÆ tentar se recuperar automaticamente na
condi(cid:231)ıes de erro na comunica(cid:231)ªo entre m(cid:243)dulos, erro no transporte, sensores inoperantes e outras
situa(cid:231)ıes; porØm, limitando-se a efetuar o procedimento espec(cid:237)fico da fun(cid:231)ªo chamada.
15. Diagrama esquemÆtico obrigat(cid:243)rio para implementa(cid:231)ªo das API(cid:146)s:
Programa
Configurador BBX_API’s
(Utilizado somente (Definidas neste
na instala(cid:231)ªo do documento)
terminal)
Carrega o m(cid:243)dulo
Leitura
Gera (com base no arquivo
(quando da inicializa(cid:231)ªo)
de configura(cid:231)ªo)
API 1 API 2
Arquivo de (DepositÆrio do (DepositÆrio do API n
Configura(cid:231)ªo fornecedor ou fornecedor ou ...
do modelo A) do modelo B)
16. O Fornecedor deverÆ entregar um aplicativo (modo texto) para gerar um arquivo de configura(cid:231)ªo
contendo informa(cid:231)ıes sobre o hardware instalado. O arquivo de configura(cid:231)ªo a ser gerado deve ser
em formato padronizado pelo Banco do Basil. Solicitar o formato do arquivo ao Banco do Brasil
durante o processo de desenvolvimento da API. O arquivo de configura(cid:231)ªo gerado deverÆ ser
utilizado por cada API para identifica(cid:231)ªo de hardware, carga de DLLs/SOs e para atender consultas
via BBX_HRD e pelas fun(cid:231)ıes (cid:147)Exist(cid:148).
17. Quando da chamada/carga das API(cid:146)s aqui documentadas, elas deverªo, com base no arquivo de
configura(cid:231)ªo, carregar somente a BBX API espec(cid:237)fica para o modelo de dispositivo f(cid:237)sico presente
no terminal. Com isso serªo evitadas altera(cid:231)ıes nas DLL(cid:146)s/SOs (BBX_API(cid:146)s), bem como novas re-
homologa(cid:231)ıes de terminais anteriormente validados. Para tanto, as API(cid:146)s aqui definidas (camada
BBX_API), nªo poderªo ser mudadas (recompiladas), devendo permanecer sempre as mesmas para
os diversos terminais/modelos a serem implementados.
18. O segundo n(cid:237)vel deve conter somente um m(cid:243)dulo para tratamento de cada hardware diferente. Por
exemplo, se o fornecedor tiver mÆquinas com 3 impressoras de recibos diferentes, deverÆ fornecer
exatamente 3 implementa(cid:231)ıes de driver da API BBXRPR, uma para cada hardware, com os mesmas
defini(cid:231)ıes/prot(cid:243)tipos aqui definidos. Nªo serªo aceitos outros m(cid:243)dulos, libs, DLLs/SOs, etc para
compor a API do fornecedor, alØm das DLLs/SOs de 1” e 2” n(cid:237)vel.
19. Cada m(cid:243)dulo do segundo n(cid:237)vel deverÆ seguir a seguinte nomenclatura: bbxnnn.ffn, onde nnn Ø o
nome da API, ff Ø a inicial do nome do fornecedor e n Ø um nœmero seq(cid:252)encial. Por exemplo, o
m(cid:243)dulo de tratamento da primeira impressora de recibos do fornecedor XYZ, serÆ bbxrpr.xy1, o
m(cid:243)dulo para tratamento do terceiro tipo de leitora serÆ bbxcrw.xy3.
20. Todos os nomes de arquivos e diret(cid:243)rios, criados ou referenciados, deverªo ser em minœsculo.
21. Em caso de necessidade de desenvolvimento de drivers (Ex.: para placas proprietÆrias) ou BBX
API·s que utilizem chamadas de fun(cid:231)ıes exclusivas (dependentes) do kernel, o fornecedor deverÆ
solicitar autoriza(cid:231)ªo expressa do Banco do Brasil e ainda mantŒ-los/atualizÆ-los para novas versıes
do kernel, pelo prazo de 10 anos.
PÆgina 3 de 331
Especifica(cid:231)ªo de API
22. Nªo devem ser criados e/ou utilizados drivers para acesso a portas seriais, paralelas ou USB
diferentes do que o sistema operacional disponibiliza sem expressa autoriza(cid:231)ªo do Banco do Brasil.
23. Caso seja necessÆrio a retirada da API (cid:147)WRAPER(cid:148), a carga da BBX API de 2” n(cid:237)vel deverÆ ser
transparente para a aplica(cid:231)ªo. Portanto, as BBX API·s de 2” n(cid:237)vel devem ter as mesmas
defini(cid:231)ıes/prot(cid:243)tipos das API(cid:146)s de 1” n(cid:237)vel.
24. As BBX API·s nªo podem fazer uso de threads. Se necessÆrio, efetuar consulta ao Banco, visando
libera(cid:231)ªo do uso da thread, desde que observado os itens abaixo. O Banco se dÆ o direito de
analisar o c(cid:243)digo e solicitar altera(cid:231)ıes visando a estabilidade da aplica(cid:231)ªo.
1) Nªo chamar fun(cid:231)ıes sleep ap(cid:243)s criar uma thread, se precisar que a execu(cid:231)ªo seja ordenada,
use API's de sincroniza(cid:231)ªo.
2) Para finalizar a thread deve utilizar variÆveis de controle, evitando ao mÆximo o uso de fun(cid:231)ıes
kill.
25. As BBX API·s nªo podem fazer uso de mem(cid:243)ria compartilhada, semÆforos ou filas de mensagens,
para comunica(cid:231)ªo/uso entre BBX API·s de diferentes dispositivos.
26. As BBX API's nªo podem ter vazamento de mem(cid:243)ria nem invasªo de buffers. Caso o Banco
constate algum problema relacionado a este item, a API serÆ considerada nªo homologada.
27. As BBX API's nªo poderªo gerar warnings quando compiladas com op(cid:231)ªo -Wall.
28. Com exce(cid:231)ªo de loops de contagem, os loops devem ter time-out para proteger o c(cid:243)digo de loop
infinito.
29. O Banco disponibilizarÆ as bibliotecas de manipula(cid:231)ªo de arquivos de configura(cid:231)ªo e log.
30. As BBX API·s nªo podem fazer uso bibliotecas compartilhadas (Ex bibliotecas de fun(cid:231)ıes utilitÆrias)
ou de variÆveis externas ao m(cid:243)dulo.
31. Independente de Sistema Operacional ou compilador, todos os m(cid:243)dulos devem ser
codificados/desenvolvidos utilizando-se o padrªo (cid:147)ANSI C(cid:148).
O Banco se reserva no direito de efetuar altera(cid:231)ıes nas fun(cid:231)ıes definidas, sem (cid:244)nus
adicionais, durante o processo de homologa(cid:231)ªo do hardware e das API(cid:146)s, para adequar as
caracter(cid:237)sticas de hardware do equipamento adquirido (cid:224)s necessidades da aplica(cid:231)ªo, com o
objetivo de manter o atendimento dos requisitos do neg(cid:243)cio, de funcionalidade e de seguran(cid:231)a
da solu(cid:231)ªo.
Mapeamento das teclas do terminal
O software do Banco espera que o hardware, a n(cid:237)vel de firmware dos teclados, responda com os
mesmos valores de retorno de um teclado normal (scan code).
Para os teclados especiais do terminal, espera-se que o firmware do hardware retorne os
c(cid:243)digos de acordo com o mapeamento abaixo.
Os oito botıes da tela do terminal deverªo retornar os c(cid:243)digos de acordo com o mapeamento a
seguir:
Tecla C(cid:243)digo retornado (scan code)
Primeira tecla (cid:224) esquerda do v(cid:237)deo (cima para Tecla F2
baixo)
Segunda tecla (cid:224) esquerda do v(cid:237)deo Tecla F3
Terceira tecla (cid:224) esquerda do v(cid:237)deo Tecla F4
Quarta tecla (cid:224) esquerda do v(cid:237)deo Tecla F5
Primeira tecla (cid:224) direita do v(cid:237)deo (cima para baixo) Tecla F6
Segunda tecla (cid:224) direita do v(cid:237)deo Tecla F7
Terceira tecla (cid:224) direita do v(cid:237)deo Tecla F8
Quarta tecla (cid:224) direita do v(cid:237)deo Tecla F9
PÆgina 4 de 331
Especifica(cid:231)ªo de API
O teclado pin deverÆ retornar os c(cid:243)digos de acordo com o mapeamento abaixo:
Tecla C(cid:243)digo retornado (scan code)
NumØricas de 0 a 9 teclas 0 a 9
Contendo o s(cid:237)mbolo "X" Tecla X
FIM ou ENTRA tecla ENTER
CORRIGE tecla BACKSPACE
CANCELA tecla ESC
Seta para a direita tecla RIGHT
Seta para a esquerda tecla LEFT
Modelo de monitora(cid:231)ªo
O rol dos eventos a serem notificados sªo os constantes da tabela de eventos inclusa no final
deste documento. Inexistindo erro junto a tabela, o fabricante deverÆ solicitar ao Banco sua inclusªo.
Qualquer erro ou evento de monitora(cid:231)ªo encontrado em qualquer dispositivo serÆ reportado ao
m(cid:243)dulo de monitora(cid:231)ªo atravØs da fun(cid:231)ªo apontada pelo ponteiro FunctionPtr, apontado abaixo.
A Fun(cid:231)ªo de Notifica(cid:231)ªo, registrada como FunctionPtr, Ø passada como argumento nas fun(cid:231)ıes
de inicializa(cid:231)ªo de cada m(cid:243)dulo e tem o seguinte formato:
Void ( * FunctionPtr ) ( agBBX * pfDescMon,
unsigned int uiDeviceId,
unsigned int uiEvent )
Par(cid:226)metros
agBBX * pfDescMon Ponteiro de descri(cid:231)ªo de Monitora(cid:231)ªo, vide as fun(cid:231)ıes de
inicializa(cid:231)ªo da unidade (em desuso (cid:150) passar vlr. (cid:147)NULL(cid:148)).
unsigned uiDeviceId Identificador do Dispositivo ou unidade definidos no include
int (cid:145)BBXDEFS.H(cid:146)
unsigned uiEvent C(cid:243)digo do evento definido na tabela de eventos inclusa neste
int cap(cid:237)tulo
Recomenda(cid:231)ıes para gera(cid:231)ªo de DLL da API BBX
Abaixo seguem recomenda(cid:231)ıes que poderªo auxiliar/facilitar o processo de gera(cid:231)ªo das DLL’s
da API BBX, de modo a facilitar a integra(cid:231)ªo com o software do Banco.
Ambiente: SuSE Linux Enterprise Server (SLES) 11 SP1 32 e 64 bits, HedHat Enterprise
Desktop 5, e versıes superiores.
Ambiente: MS-Windows 7 Professional, em formato de m(cid:243)dulos de liga(cid:231)ªo din(cid:226)mica (DLL)
32 e 64 bits, e versıes superiores.
Oportunamente serÆ informado ao vencedor do processo licitat(cid:243)rio os par(cid:226)metros
de compila(cid:231)ªo de APIs.
PÆgina 5 de 331
Especifica(cid:231)ªo de API
Cap(cid:237)tulo 1 Unidade Impressora de Recibo
1.1 Introdu(cid:231)ªo
Este cap(cid:237)tulo define as fun(cid:231)ıes da Interface do Programa de Aplica(cid:231)ªo (API), para a Unidade
Impressora de Recibo (RPR).
Fontes de impressªo RPR
A unidade RPR deverÆ possuir a fonte multilingual padrªo 850.
Controle de impressªo RPR
A unidade RPR deverÆ suportar, pelo menos, os seguintes controles de impressªo:
 0x0D Carriage Return (CR) Posicionar a cabe(cid:231)a da impressora para a margem esquerda na
linha atual.
 0x0A Line Feed (LF) Posicionar a cabe(cid:231)a da impressora para a linha seguinte na
posi(cid:231)ªo da linha atual.
Os demais c(cid:243)digos de controle deverªo ser passados diretamente para a impressora.
Estados RPR
De acordo com as fun(cid:231)ıes API, a unidade RPR poderÆ, a qualquer momento, estar em um dos
seguintes estados:
RPR com presenter:
 Estado livre
A unidade RPR nªo foi iniciada, estÆ liberada e nªo estÆ operacional.
 Estado operacional
A unidade RPR foi iniciada e encontra-se operacional.
 Estado de espera de retirada do recibo
O recibo estÆ na sa(cid:237)da da unidade RPR (cid:224) espera de ser retirado.
RPR desprovida de presenter:
 Estado livre
A unidade RPR nªo foi iniciada, estÆ liberada e nªo estÆ operacional.
 Estado operacional
A unidade RPR foi iniciada e encontra-se operacional.
PÆgina 6 de 331
Especifica(cid:231)ªo de API
1.2 ReferŒncia ao Diagrama de Estado da RPR
RPR com presenter:
ReceiptAtExit()
(recibo na sa(cid:237)da)
ReleasePresenter
() ReceiptEjectTimeout()
(tempo nªo esgotado)
ReceiptPrint()
Status()
Status()
Initialize(
ReceiptEject ()
)
Espera de
Livre Operacional retirada de
(led desligado) (led desligado) recibo
ReceiptAtExit() (led piscando)
Terminate(
(recibo nªo estÆ na
)
sa(cid:237)da)
ReceiptEjectTimeout
()
(tempo esgotado)
PÆgina 7 de 331
Especifica(cid:231)ªo de API
RPR desprovida de presenter:
ReceiptPrint()
Status()
Initialize()
Livre Operacional
(led desligado) (led desligado)
Terminate()
Observa(cid:231)ıes:
 RPR desprovida de presenter:
 ReceiptEject() - Retorna sempre BBX_API_OK
 ReceiptAtExit() - Retorna sempre FALSE
 ReceiptEjectTimeout() - Retorna sempre TRUE
 ReleasePresenter() - Retorna sempre BBX_API_OK

PÆgina 8 de 331
Especifica(cid:231)ªo de API
1.3 BBX_RPR_Initialize

Descri(cid:231)ªo
Esta fun(cid:231)ªo inicia a unidade RPR.
Prot(cid:243)tipo
int BBX_RPR_Initialize ( void * pvCallBackDescMon)

Par(cid:226)metros
void * pvCallBackDescMon Ponteiro para a fun(cid:231)ªo de notifica(cid:231)ªo de eventos. Ver tabela de erros
no anexo.

Valores de Retorno
BBX_API_OK (0) Sem erros - RPR iniciada
BBX_API_ERROR (-1) Erro
ComentÆrios
A inicializa(cid:231)ªo da unidade RPR deverÆ ser realizada antes da utiliza(cid:231)ªo de qualquer outra
fun(cid:231)ªo API da unidade RPR.
A API, nesta fun(cid:231)ªo, deverÆ registrar a versªo de firmware do m(cid:243)dulo impressora de recibos no
log do fornecedor. Sempre que o firmware do m(cid:243)dulo for diferente da versªo especificada no arquivo
BBXRPR.INI, a API deve gerar monitora(cid:231)ªo conforme tabela abaixo.

BBXRPR.INI estÆ em Versªo incorreta de Gerar monit(1,13) Registrar versªo de
/home/term/base firmware do m(cid:243)dulo firmware no log
SIM SIM X X
SIM NˆO X
NˆO N/A X
onde:
N\A = nªo se aplica.
BBXRPR.INI = arquivo que contØm informa(cid:231)ıes das versıes de firmware vÆlidas, com o seguinte lay-out:
[firmware]
versªo = XXXXXX;YYYYY ( onde XXXXX;YYYYY = versıes vÆlidas)

1.4 BBX_RPR_Terminate

Descri(cid:231)ªo
Esta fun(cid:231)ªo libera a unidade RPR.
PÆgina 9 de 331
Especifica(cid:231)ªo de API
Prot(cid:243)tipo
int BBX_RPR_Terminate ( void )

Par(cid:226)metros
nenhum

Valores de Retorno
BBX_API_OK (0) Sem erros - RPR liberada
BBX_API_ERROR (-1) Erro
ComentÆrios

1.5 BBX_RPR_ReceiptEject

Descri(cid:231)ªo
Esta fun(cid:231)ªo fornece o recibo atual ao cliente, iniciando a contagem de um limite de tempo para
que o cliente retire o recibo.
Esta fun(cid:231)ªo retornarÆ imediatamente, o processo de chamada nªo Ø bloqueado.
Prot(cid:243)tipo
int BBX_RPR_ReceiptEject ( unsigned int uiTimeToWait )

Par(cid:226)metros
unsigned int uiTimeToWait Tempo de espera para o recibo ser retirado em centØsimos de
segundos

Valores de Retorno
BBX_API_OK (0) Sem erros - Recibo retirado
BBX_API_ERROR (-1) Erro
ComentÆrios
A contagem do tempo Ø automaticamente interrompida quando o recibo Ø retirado antes que o
limite de tempo seja esgotado. Para verificar a contagem de tempo serÆ utilizada a fun(cid:231)ªo
(cid:145)BBX_RPR_ReceiptEjectTimeout(cid:146) e para verificar se o recibo foi retirado, serÆ utilizada a fun(cid:231)ªo
(cid:145)BBX_RPR_ReceiptAtExit(cid:146).

1.6 BBX_RPR_ReceiptPrint

Descri(cid:231)ªo
Esta fun(cid:231)ªo imprime os dados para o recibo.
PÆgina 10 de 331