Resumo

O KQueryServer é um serviço que permite a obtenção de dados referentes à configuração e estado atual de dispositivos e da API K3L, além do envio de alguns comandos. Isso é feito através de requisições em formato pré-definido baseado no KSNMP, um agente do protocolo SNMP que fornece as informações da API K3L para consulta, no qual uma requisição é formada por números separados por pontos. Diferentemente, o KQueryServer utiliza-se de mnemônicos para indicar o dado que deseja consultar, porém respeitando a organização definida pelo KSNMP. Por exemplo, "k3l.DeviceCount" requisita a quantidade de dispositivos configurados e "k3l.DeviceType.4242" requisita o tipo do dispositivo cujo número de série é 4242. Dessa forma, pode-se obter dados do sistema através de uma conexão TCP e assim utilizar essa ferramenta para construção de scripts e/ou aplicações Web.

Para realizar a comunicação com o KQueryServer, é necessário estabelecer uma conexão com o serviço através de um Socket TCP, que por padrão utiliza a porta 14130. 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 como pode ser visto na seção EBS. Para informações detalhadas sobre como enviar requisições e receber respostas, vide a seção Utilizando o KQueryServer.

O KQueryServer também pode ser usado para responder requisições como um Agente Proxy para o SNMP. Dessa forma, o KQueryServer funcionará como um sub-agente compatível com Net-SNMP, trabalhando em conjunto com outros agentes presentes no sistema. A seção Utilizando o KQueryServer como Proxy SNMP explica como integrar ao Net-SNMP e a seção Requisições Disponíveis mostra a requisição SNMP equivalente a cada requisição do KQueryServer.



Formatos de Requisição


QUERY <string>

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

Exemplo:
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:
CMD k3l.ResetLink.12345.1
Resposta:
Executed


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:
3QUERY k3l.DeviceCount;QUERY k3l.Device.Type.12345;QUERY k3l.Config.Device.12345.ChannelCount$
Resposta 1:
3;18;60
Exemplo 2:
2QUERY k3l.Status.Connected.12345|QUERY k3l.Status.Connected.54321$
Resposta 2:
0|1
Exemplo 3:
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)



Requisições Disponíveis


As requisições estão apresentadas como Query | SNMP, ou seja, o lado esquerdo do '|' mostra a query no formato de mnemônicos e, à direita, o formato correspondente para o SNMP.

Importante! Os parâmetros 'Link' e 'Canal' começam a contagem a partir de 1 nas requisições SNMP.

Importante! Uma requisição SNMP começa com 1.3.6.1.4.1.32624. seguido pelas sequências númericas apresentadas a seguir.

Configuração

k3l.DeviceCount | 1.1.0

k3l.DeviceType.X | 1.2.X.0

k3l.Config.Device.X.LinkCount | 1.3.1.X.1.0

k3l.Config.Device.X.ChannelCount | 1.3.1.X.2.0

k3l.Config.Device.X.EnabledChannelCount | 1.3.1.X.3.0

k3l.Config.Device.X.DeviceModel | 1.3.1.X.7.0

k3l.Config.Device.X.VoIPChannelCount | 1.3.1.X.12.0

k3l.Config.Device.X.SerialNumber | 1.3.1.X.16.0

k3l.Config.Link.X.Y.Signaling | 1.3.2.X.Y.1.0

k3l.Config.Link.X.Y.Name | 1.3.2.X.Y.7.0

k3l.Config.Link.X.Y.OperatingMode | 1.3.2.X.Y.8.0

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

k3l.Config.Link.X.Y.ReceivingClock | 1.3.2.X.Y.9.0

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

k3l.Config.Channel.X.Y.Signaling | 1.3.3.X.Y.1.0

k3l.Config.Api.StrVersion | 1.3.5.7.0

k3l.Config.Api.R2Country | 1.3.5.8.0

k3l.Config.EBS.X.String | 1.3.6.X.1.0

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

k3l.Config.EBS.X.GSMChannels | 1.3.6.X.2.0

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

k3l.Config.EBS.X.IP | 1.3.6.X.3.0

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


Estado

k3l.Status.Link.X.Y.E1 | 1.4.1.X.Y.1.0

k3l.Status.Link.X.Y.Z.E1 | 1.4.1.X.Y.Z.1.0

k3l.Status.Link.X.Y.Z.Channels | 1.4.1.X.Y.Z.2.0

k3l.Status.Link.X.Y.HI | 1.4.1.X.Y.3.0

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

k3l.Status.Channel.X.Y.CallStatus | 1.4.2.X.Y.1.0

k3l.Status.Channel.X.Y.AudioStatus | 1.4.2.X.Y.2.0

k3l.Status.Channel.X.Y.AddInfo | 1.4.2.X.Y.3.0

k3l.Status.Channel.X.Y.EnabledFeatures | 1.4.2.X.Y.4.0

k3l.Status.Channel.X.TotalFail | 1.4.2.X.5.0

k3l.Status.Channel.X.TotalIdle | 1.4.2.X.6.0

k3l.Status.Channel.X.TotalCall | 1.4.2.X.7.0

k3l.Status.Channel.X.Y.DialNumber | 1.4.2.X.8.0

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

k3l.Status.Channel.X.Y.CallDuration | 1.4.2.X.9.0

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

k3l.Status.Channel.X.Y.RecordingStatus | 1.4.2.X.10.0

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

k3l.Status.Channel.X.Y.AverageCallTime | 1.4.2.X.11.0

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

k3l.Status.LinkErrorCounter.X.Y | 1.4.4.X.Y.0

k3l.Status.GSMChannel.X.Y.SignalStrength.Z | 1.4.5.X.Y.1.Z.0

k3l.Status.GSMChannel.X.Y.ErrorRate.Z | 1.4.5.X.Y.2.Z.0

k3l.Status.GSMChannel.X.Y.RegistryStatus.Z | 1.4.5.X.Y.3.Z.0

k3l.Status.GSMChannel.X.Y.OperName.Z | 1.4.5.X.Y.4.Z.0

k3l.Status.GSMChannel.X.Y.UnreadSmsCount.Z | 1.4.5.X.Y.5.Z.0

k3l.Status.GSMChannel.X.Y.EnabledFeatures.Z | 1.4.5.X.Y.6.Z.0

k3l.Status.GSMChannel.X.Y.IMEI.Z | 1.4.5.X.Y.7.Z.0

k3l.Status.GSMChannel.X.Y.SIM.Z | 1.4.5.X.Y.8.Z.0

k3l.Status.GSMChannel.X.Y.CallStatus.Z | 1.4.5.X.Y.9.Z.0

k3l.Status.GSMChannel.X.Y.IMSI.Z | 1.4.5.X.Y.10.Z.0

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

k3l.Status.GSMChannel.X.Y.ICCID.Z | 1.4.5.X.Y.11.Z.0

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

k3l.Status.Connected.X | 1.4.6.X.0


Estatística

k3l.ChannelStats.X.Y | 1.5.X.Y.0


VoIP

SIP

voip.GW.Profile.X.LocalAddress

voip.GW.Profile.X.LocalPort

voip.GW.Profile.X.TransportType

voip.GW.Profile.X.RTPAddress

voip.GW.Profile.X.User

voip.GW.Profile.X.AuthorizationUser

voip.GW.Profile.X.Realm

voip.GW.Profile.X.Domain

voip.GW.Profile.X.DomainPort

voip.GW.Profile.X.Proxy

voip.GW.Profile.X.ProxyPort

voip.GW.Profile.X.Registered


RTP

voip.Media.RTPStatus.X.Transmit.LastSequenceNumber

voip.Media.RTPStatus.X.Transmit.PacketCount

voip.Media.RTPStatus.X.Transmit.OctetCount

voip.Media.RTPStatus.X.Transmit.PacketLost

voip.Media.RTPStatus.X.Receive.InitialSequenceNumber

voip.Media.RTPStatus.X.Receive.LastSequenceNumber

voip.Media.RTPStatus.X.Receive.PacketCount

voip.Media.RTPStatus.X.Receive.DroppedCount

voip.Media.RTPStatus.X.Receive.LastDroppedCount

Comandos Disponíveis

k3l.ResetLink.X.Y

k3l.ClearLinkErrorCounter.X.Y

k3l.BlockLink.X.Y

k3l.ResetModem.X.Y

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

k3l.ClearChannelStats.X.Y

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


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 o KQueryServer como Proxy SNMP

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).