Índice

Resumo

O KQueryServer é um serviço que permite obter dados referentes à configuração e estado atual de dispositivos e da API K3L.

Isso é feito através de requisições em um formato baseado no SNMP, podendo ser usado através de MIB (Management Information Base) e/ou OID (Object IDentification). A MIB é a base de informações de gerenciamento e um OID é o identificador único dentro da MIB. Para isso é necessário estabelecer uma conexão com o serviço através de uma conexão UDP, na porta 14161, utilizando o comunidade "khomp", nessa conexão transitam as requisições e suas respectivas respostas.

As respostas serão sempre codificadas como sequências de caracteres, representando valores numéricos e índices, ou nomes e identificação de recursos, dependendo da requisição. Quando a requisição for SNMP legada a resposta será um índice de um valor enumerado podendo ser verificado na página EBS.

A partir da versão 3.3 da API, a interface SNMP foi reformulada para possibilitar sua formalização na forma da RFC 1213 (Management Information Base - MIB-II). O arquivo "KHOMP-MIB" é disponibilizado junto com pacote da API e está localizado no seguinte caminho:

Windows:

c:\ProgramData\Khomp\

Linux:

 /etc/khomp/
NOTA: A interface legada SNMP permanece sendo suportada para todas as queries definidas até esta versão. Queries implementadas após esta versão poderão ser suportadas somente no modo formalizado.

Formato de requisições

As requisições estão apresentadas como Query (Modo Compatibilidade) | SNMP legada | MIB, ou seja, o primeiro formato apresentado serão os mnemônicos e, no centro, o formato correspondente para o SNMP legada e por fim à direita o formato recomendado pela Khomp, que utiliza o formato MIB, prefixado por KHOMP-MIB::

NOTA: Algumas requisições não estão disponíveis em todos os formatos.

Exemplos

MIB

Na requisição abaixo é utilizado o formato MIB, prefixado por KHOMP-MIB::, no qual requisita ao servidor a quantidade de dispositivos configurados.

Exemplo 1:
snmpget -v1 -c khomp <IP_SERVIDOR>:14161 -m +KHOMP-MIB -M +/etc/khomp KHOMP-MIB::k3lDeviceCount.0
Resposta: KHOMP-MIB::k3lDeviceCount.0 = Gauge32: 7

onde:

Abaixo requisita ao servidor qual é o tipo do dispositivo, nesse exemplo é preciso informar o número do serial do dispositivo.

Exemplo 2:
snmpget -v1 -c khomp <IP_SERVIDOR>:14161 -m +KHOMP-MIB -M +/etc/khomp KHOMP-MIB::k3lDeviceType.49845
Resposta: KHOMP-MIB::k3lDeviceType.49845 = INTEGER: kdtEBSE1(18)

SNMP legada

Nesse exemplo verifique que foi utilizado o formato SNMP legada, prefixado por .1.3.6.1.4.1.32624., na qual também requisita ao servidor a quantidade de dispositivos configurados.

Exemplo 1:
snmpget -v1 -c khomp <IP_SERVIDOR>:14161 .1.3.6.1.4.1.32624.1.1.0
Resposta: iso.3.6.1.4.1.32624.1.1.0 = STRING: "7"

Abaixo requisita ao servidor qual é o tipo do dispositivo, nesse exemplo é preciso informar o número do serial do dispositivo.

Exemplo 2:
snmpget -v1 -c khomp <IP_SERVIDOR>:14161 .1.3.6.1.4.1.32624.1.2.49845.0
Resposta: iso.3.6.1.4.1.32624.1.2.49845.0 = STRING: "18"

O retorno da requisição pode ser verificado no seguinte link: Códigos de Descrição e Estado da K3L.

ATENÇÃO: Os parâmetros 'Link' e 'Canal' começam a contagem a partir de 1 (um) nas requisições SNMP legadas. Nas requisições que utilizam a MIB como referência, a contagem começa em 0 (zero), sendo 0 tambem mapeado para o primeiro canal.


ATENÇÃO: Uma requisição SNMP legada deve ser iniciada por 1.3.6.1.4.1.32624. seguido pelas sequências numéricas apresentadas a seguir ou KHOMP-MIB::legacy., sendo necessário remover o primeiro dígito da sequencia numérica.

Requisições Disponíveis

Informações de operação do sistema

Quantidade de dispositivos configurados

Versão da API

País do padrão de troca de MFC utilizado pelo R2

Quantidade total de canais no sistema

Quantidade total de canais habilitados

Quantidade total de canais livres

Quantidade total de canais ocupados

Quantidade total de canais em falha

Dispositivo

Tipo do dispositivo

Modelo do dispositivo

Número Serial do dispositivo

Quantidade de Links do dispositivo

Quantidade de canais do dispositivo

Quantidade de canais habilitados no dispositivo

Quantidade de canais VoIP do dispositivo

Quantidade de canais livres

Quantidade de canais ocupados

Quantidade de canais em falha

Endereço IP do EBS

Este recurso está disponível a partir da versão: 3.3.

Estado de operação do dispositivo

EBS Modular

Nome do EBS Modular

Este recurso está disponível a partir da versão: 3.1.

Quantidade de grupos no dispositivo

Índice do grupo

Tipo do grupo

Índice do primeiro canal do grupo

Quantidade de canais do grupo

Quantidade de canais disponíveis do grupo

Quantidade de canais em falha do grupo

Quantidade de canais ocupados do grupo

Números dos canais GSM presentes no EBS Modular

Este recurso está disponível a partir da versão: 3.1.

Link

Sinalização do link

Nome atribuído ao link na configuração

Retorna 'E1' ou 'T1' para indicar o modo de operação do link

Este recurso está disponível a partir da versão: 3.3.

Indica se o link está recebendo a sincronização

Este recurso está disponível a partir da versão: 3.3.

Quantidade de canais do link

Este recurso está disponível a partir da versão: 3.3.

Quantidade de canais habilitados no link

Este recurso está disponível a partir da versão: 3.3.

Quantidade de canais livres no link

Este recurso está disponível a partir da versão: 3.3.

Quantidade de canais ocupados no link

Este recurso está disponível a partir da versão: 3.3.

Quantidade de canais com falha no link

Este recurso está disponível a partir da versão: 3.3.

Contadores de erros do link

Estado simplificado do link (UP,DOWN)

Este recurso está disponível a partir da versão: 3.3.

Estado de alarme do link

Retorna, separadamente, o estado simplificado (UP,DOWN) dos Rx de um link de gravação passiva.

Este recurso está disponível a partir da versão: 3.3.

Retorna, separadamente, o estado dos Rx de um link de gravação passiva

Este recurso está disponível a partir da versão: 3.1.

Canal

Sinalização do canal

Estado do canal

Estado extendido por sinalização

Estado do áudio no canal

Recursos habilitados

Indica se o canal está gravando

Este recurso está disponível a partir da versão: 3.2.

Indica se o canal está com uma cadência ativa

Este recurso está disponível a partir da versão: 3.5.

Chamada

Estado da chamada

Número discado na ligação corrente

Este recurso está disponível a partir da versão: 3.2.

Número de origem na ligação corrente

Este recurso está disponível a partir da versão: 3.3.1.

Duração da ligação corrente em milissegundos

Este recurso está disponível a partir da versão: 3.2.

Estatisticas de Chamadas

Dispositivo

Quantidade de chamadas entrantes

Quantidade de chamadas saintes

Quantidade de chamadas saintes completadas

Quantidade de erros em chamadas saintes

Quantidade de chamadas que sofreram desconexão remota

Quantidade de erros que sofreram desconexão local

Quantidade de erros em chamadas ocupadas

Quantidade de erros em chamadas sem resposta

Quantidade de erros em chamadas rejeitadas

Quantidade de erros em chamadas cujo numero de destino mudou

Quantidade de erros em chamadas de numero invalido

Quantidade de erros em chamadas fora de serviço

Quantidade de erros devido a congestionamento na linha

Quantidade de erros devido a falha na rede

Quantidade de erros em chamadas (outros)

Link

Quantidade de chamadas entrantes no link

Quantidade de chamadas saintes no link

Quantidade de chamadas saintes completadas no link

Quantidade de erros em chamadas saintes no link

Quantidade de chamadas no link que sofreram desconexão remota

Quantidade de erros no link que sofreram desconexão local

Quantidade de erros em chamadas ocupadas

Quantidade de erros em chamadas sem resposta

Quantidade de erros em chamadas rejeitadas

Quantidade de erros em chamadas cujo numero de destino mudou

Quantidade de erros em chamadas de numero invalido

Quantidade de erros em chamadas fora de serviço

Quantidade de erros devido a congestionamento na linha

Quantidade de erros devido a falha na rede

Quantidade de erros em chamadas (outros)

Canal

Média da duração das ligações do canal, em segundos

Este recurso está disponível a partir da versão: 3.3.

Contadores separados por canal

GSM

Nível de sinal

Taxa de erros

Estado do registro

Nome da operadora

Número de SMS não lidos

Recursos habilitados

Retorna o número IMEI

SIM card atualmente selecionado

Estado da chamada Z no canal Y

Retorna o número IMSI

Este recurso está disponível a partir da versão: 3.2.4.

Retorna o número ICCID

Este recurso está disponível a partir da versão: 3.2.4.

Retorna o número MSISDN

Este recurso está disponível a partir da versão: 3.3.1.

Retorna o estado do recurso de Call Waiting

Este recurso está disponível a partir da versão: 3.3.3.

Retorna o numeo de SIM cards no modem

Este recurso está disponível a partir da versão: 3.3.7.

VoIP


SIP

Perfil

Endereço local utilizado para preencher as mensagens SIP.
Porta local utilizada para preencher as mensagens SIP.
Tipo de transporte (UDP ou TCP) utilizado para preencher as mensagens SIP.
Endereço local utilizado para a troca de áudio RTP
"Address of Record" utilizado no registro
Parâmetro "username" utilizado no campo "Authorization".
Parâmetro "realm" utilizado no campo "Authorization"
Endereço do servidor onde será feito o registro.
Porta do servidor onde será feito o registro
Endereço do proxy por onde a mensagem deve passar antes de chegar no servidor
Porta do proxy por onde a mensagem deve passar antes de chegar no servidor
Indica se o profile está registrado ou não em um servidor

Canal

Número de transações.
Número de transações cliente.
Este recurso está disponível a partir da versão: 3.3.6.
Número de transações servidora.
Este recurso está disponível a partir da versão: 3.3.6.
Número de transações cliente com falha
Este recurso está disponível a partir da versão: 3.3.6.
Número de transações servidora com falha
Este recurso está disponível a partir da versão: 3.3.6.
Número de transações cliente com falha (código de erro 4xx)
Este recurso está disponível a partir da versão: 3.3.6.
Número de transações servidora com falha (código de erro 4xx)
Este recurso está disponível a partir da versão: 3.3.6.
Número de transações cliente com falha (código de erro 5xx)
Este recurso está disponível a partir da versão: 3.3.6.
Número de transações servidora com falha (código de erro 5xx)
Este recurso está disponível a partir da versão: 3.3.6.
Número de transações cliente com falha (código de erro 6xx)
Este recurso está disponível a partir da versão: 3.3.6.
Número de transações servidora com falha (código de erro 6xx)
Este recurso está disponível a partir da versão: 3.3.6.

RTP

Número de sequência do último pacote RTP enviado

Número de pacotes RTP enviados

Número total de octetos RTP enviados

Número de pacotes RTP enviados perdidos

Número de sequência do primeiro pacote RTP recebido

Número de sequência do último pacote RTP recebido

Número de pacotes RTP recebidos

Quantidade total de pacotes entrantes perdidos

Quantidade de pacotes entrantes perdidos em sequência

SS7


ISUP

Retorna uma lista com os nomes dos grupos de circuitos presentes no arquivo de configuração

Retorna o point code de origem (originating point code)

Retorna o point code de destino (destination point code)

Retorna o código de identificação do circuito (circuit identification code) inicial

Indica se representa um grupo de sinalização passiva

Retorna o número de circuitos

Retorna o mapa de timeslot

Retorna o endereço IP onde está localizado o grupo de circuito

Retorna o número de série da placa, localizada na máquina informada pelo campo address

Retorna o número do link, localizado na máquina e placa informadas pelos campos address e device

Indica se o call control do grupo está ativo

Indica se o link da placa está ativo (informado pelo HDLC)

Indica se algum link mtp3 está ativo para o grupo de circuito (informado pelo MTP3)

Retorna o valor do timer resume (em milissegundos)

Retorna o valor do timer pause (em milissegundos)

Retorna uma lista com os valores dos códigos de identificação do circuito do grupo do circuito

Retorna o valor do identificador global único do circuito

Retorna o status presente na máquina de estados do SS7 do circuito

Retorna o valor do timer T1

Retorna o valor do timer T5

Retorna o valor do timer T6

Retorna o valor do timer T7

Retorna o valor do timer T8

Retorna o valor do timer T9

Retorna o valor do timer T12

Retorna o valor do timer T13

Retorna o valor do timer T14

Retorna o valor do timer T15

Retorna o valor do timer T16

Retorna o valor do timer T17

Retorna o valor do timer T18

Retorna o valor do timer T19

Retorna o valor do timer T20

Retorna o valor do timer T21

Retorna o valor do timer T22

Retorna o valor do timer T23

Retorna o valor do timer T24

Retorna o valor do timer T25

Retorna o valor do timer T26

Retorna o valor do timer T27

Retorna o valor do timer T28

Retorna o valor do timer T34

Retorna o valor do timer T36

Retorna o valor do timer T37

Retorna o valor do timer T38

Retorna o número de circuitos licenciados

Indica se o circuito com identificador global de número X está licenciado


MTP3

Retorna uma lista com os nomes dos linksets presentes no arquivo de configuração

Retorna o identificador do linkset

Retorna o point code de origem

Retorna o point code adjacente

Retorna o indicador de rede

Indica se o linkset está ativo

Retorna uma lista com os nomes dos links pertencentes ao linkset

Retorna o nome do link MTP2

Retorna o SLC

Retorna o valor do timer Q.707 T1

Retorna o valor do timer Q.707 T2

Retorna o valor do timer Q.704 T17

Indica se o link está disponível

Indica se o link está em serviço

Indica se a ativação está em progresso

Indica se o link está ativado

Indica se o link está bloqueado

Indica se o link está no estado inhibited

Indica se o link está no estado remote processor outage

Retorna uma lista com os nomes das rotas existentes

Retorna o point code cadastrado

Retorna uma lista com os nomes dos linksets da rota X

MTP2

Retorna uma lista com os nomes dos links MTP2 presentes no arquivo de configuração

Retorna o endereço

Retorna o dispositivo

Retorna o link

Retorna o timeslot

Indica se o link é passivo

Retorna o valor do timer T1

Retorna o valor do timer T2

Retorna o valor do timer T3

Retorna o valor do timer T5

Retorna o valor do timer T6

Retorna o valor do timer T7

Retorna o valor do timer proving emergency

Retorna o valor do timer proving normal

Point Code

Retorna uma lista com os nomes dos point codes presentes no arquivo de configuração

Retorna o primeiro campo do point code

Retorna o segundo campo do point code

Retorna o último campo do point code

Comandos Disponíveis

Reinicia o link

Zera os contadores de erro do link

Bloqueia todos os canais do link

Reinicia o modem

Este recurso está disponível a partir da versão: 3.3.

Zera as estatísticas do canal

Este recurso está disponível a partir da versão: 3.3.

Modo Compatibilidade

Para realizar a comunicação com o KQueryServer em modo de compatibilidade, é necessário estabelecer uma conexão com o serviço através de uma conexão TCP, na porta 14130 (configurável). Nessa conexão transitam as requisições e suas respectivas respostas. Essas requisições podem ser do tipo QUERY (que requisitam uma informação do sistema) ou CMD (que enviam um comando) e possuem um formato específico. As requisições do tipo QUERY podem ser concatenadas e enviadas em um único lote, o que pode diminuir consideravelmente o uso de recursos do sistema operacional em aplicações com alta demanda por informação.

Requisições Simples

QUERY <string>

Envia uma requisição simples e recebe uma resposta que pode ser verificado na página Códigos de retorno das funções.

Exemplo:
Telnet <IP_SERVIDOR>:14130
QUERY k3l.DeviceCount
Resposta: 3

CMD <string>

Envia um comando, a <string> pode ser qualquer uma das listadas na seção Códigos de retorno das funções.

Exemplo:
Telnet <IP_SERVIDOR>:14130 
CMD k3l.ResetLink.12345.1
Resposta:  Executed


OID <object id>

Este formato só disponível a partir da versão 3.3

Envia uma requisição simples utilizando o interpretador SNMP, permitindo utilizar qualquer item da MIB Khomp. Todos os resultados serão convertidos para string.

Exemplo: (requisição k3lDeviceCount)
Telnet <IP_SERVIDOR>:14130
OID .1.3.6.1.4.1.32624.2.1.2.1.0
Resposta: 3

Requisições múltiplas

Formato novo (a partir da 3.3)

Este formato só disponível a partir da versão 3.3

REQUISIÇÃO_SIMPLES_1;REQUISIÇÃO_SIMPLES_2; ... ;REQUISIÇÃO_SIMPLES_N

Envia requisições em lote. Como separador podem ser usados os caracteres ';' ou '|', não existe distinção entre eles, servindo somente para permitir agrupamentos na resposta, ficando sua utilização à cargo do usuário. O separador utilizado na requisição será utilizado na resposta na mesma posição. Qualquer requisição simples pode ser utilizada (QUERY, CMD ou OID). Caso alguma requisição falhe, as demais serão executadas normalmente e a que falhou será indicada por um "Query failed(<causa>)" na posição referente a mesma.

Exemplo 1:
Telnet <IP_SERVIDOR>:14130
QUERY k3l.DeviceCount;QUERY k3l.Device.Type.12345;QUERY k3l.Config.Device.12345.ChannelCount
Resposta 1: 3;18;60


Exemplo 2:
Telnet <IP_SERVIDOR>:14130 
OID .1.3.6.1.4.1.32624.2.1.2.1.0|QUERY k3l.Status.Connected.12345|QUERY k3l.Status.Connected.54321
Resposta 2: 3|0|1

Formato antigo (até 3.2)

Este formato não está mais disponível a partir da versão 3.3

n(QUERY <string>;)n-1QUERY <string>$

Envia requisições em lote, onde n indica o número de requisições existentes no lote e '$' indica o fim da requisição. Como separador podem ser usados os caracteres ';' ou '|', não existe distinção entre eles, servindo somente para permitir agrupamentos na resposta, ficando sua utilização à cargo do usuário. Caso alguma requisição falhe, as demais serão executadas normalmente e a que falhou será indicada por um "Query failed(<causa>)" na posição referente a mesma. Se caso o indicador de fim de lote '$' não for enviado, será retornado apenas "Batch corrupted" e nenhuma requisição será executada.

Exemplo 1:
Telnet <IP_SERVIDOR>:14130
3QUERY k3l.DeviceCount;QUERY k3l.Device.Type.12345;QUERY k3l.Config.Device.12345.ChannelCount$
Resposta 1: 3;18;60
Exemplo 2:
Telnet <IP_SERVIDOR>:14130
2QUERY k3l.Status.Connected.12345|QUERY k3l.Status.Connected.54321$
Resposta 2: 0|1
Exemplo 3:
Telnet <IP_SERVIDOR>:14130
3QUERY k3l.Status.Connected.12345;QUERY k3l.Device.TyASD.12345;QUERY k3l.ApiConfig.StrVersion$
Resposta 3: 1;Query failed(5);K3L API 3.0.0 - (rev: 11789)


Programando com KQueryServer

O esqueleto de um programa que interage com o KQueryServer enviando requisições e recebendo respostas pode ser visto no PseudoCódigo/C++ a seguir:

socket_handle = socket( AF_INET, SOCK_STREAM, SOL_TCP );
connect( socket_handle, IP_DO_SERVIDOR_RODANDO_KQUERYSERVER, 14130 );
 
for (int i = 0; i < NUMERO_DE_REQUISICOES; i++)
{
    write( socket_handle, requisicao, strlen(requisicao) );
    recv ( socket_handle, $resposta, TAMANHO_BUFFER_RESPOSTA, MSG_WAITALL );
}
 
close( socket_handle );

Utilizando snmpd como proxy para o KQueryServer

Para integrar o KQueryServer à uma solução de SNMP já utilizada pelo usuário, será necessário somente configurar o seu agente atual para utilizar o KQueryServer como um sub-agente. Para isso, basta adicionar no arquivo snmpd.conf:

rocommunity  public
proxy -v 1 -c khomp localhost:14161 .1.3.6.1.4.1.32624

aonde:

Assim, todas as requisições que comecem com '1.3.6.1.4.1.32624' serão redirecionadas para o KQueryServer que esteja rodando no IP e porta especificados. O KQueryServer terá as mesmas funcionalidades do KSNMP (com a adição de algumas requisições atualmente não disponíveis).