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
- Parâmetros: Nenhum
- Retorno: int
- Descrição: Quantidade de dispositivos configurados
k3l.DeviceType.X | 1.2.X.0
- Parâmetros: X = Serial
- Retorno: int (KDeviceType)
- Descrição: Tipo do dispositivo X
k3l.Config.Device.X.LinkCount | 1.3.1.X.1.0
- Parâmetros: X = Serial
- Retorno: int
- Descrição: Quantidade de Links do dispositivo
k3l.Config.Device.X.ChannelCount | 1.3.1.X.2.0
- Parâmetros: X = Serial
- Retorno: int
- Descrição: Quantidade de canais do dispositivo
k3l.Config.Device.X.EnabledChannelCount | 1.3.1.X.3.0
- Parâmetros: X = Serial
- Retorno: int
- Descrição: Quantidade de canais habilitados no dispositivo
k3l.Config.Device.X.DeviceModel | 1.3.1.X.7.0
- Parâmetros: X = Serial
- Retorno: int (K*DeviceModel)
- Descrição: Modelo do dispositivo
k3l.Config.Device.X.VoIPChannelCount | 1.3.1.X.12.0
- Parâmetros: X = Serial
- Retorno: int
- Descrição: Quantidade de canais VoIP do dispositivo
k3l.Config.Device.X.SerialNumber | 1.3.1.X.16.0
- Parâmetros: X = ID na K3L
- Retorno: int
- Descrição: Número Serial do dispositivo
k3l.Config.Link.X.Y.Signaling | 1.3.2.X.Y.1.0
- Parâmetros: X = Serial, Y = Link
- Retorno: int (KSignaling)
- Descrição: Sinalização do link
k3l.Config.Link.X.Y.Name | 1.3.2.X.Y.7.0
- Parâmetros: X = Serial, Y = Link
- Retorno: string
- Descrição: Nome atribuído ao link na configuração
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.
|
- Parâmetros: X = Serial, Y = Link
- Retorno: string
- Descrição: Retorna 'E1' ou 'T1' para indicar o modo de operação do link
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.
|
- Parâmetros: X = Serial, Y = Link
- Retorno: bool
- Descrição: Indica se o link está recebendo a sincronização
k3l.Config.Channel.X.Y.Signaling | 1.3.3.X.Y.1.0
- Parâmetros: X = Serial, Y = Canal
- Retorno: int (KSignaling)
- Descrição: Sinalização do canal
k3l.Config.Api.StrVersion | 1.3.5.7.0
- Parâmetros: Nenhum
- Retorno: string
- Descrição: Versão da API
k3l.Config.Api.R2Country | 1.3.5.8.0
- Parâmetros: Nenhum
- Retorno: int (KR2Country)
- Descrição: País do padrão de troca de MFC utilizado pelo R2
k3l.Config.EBS.X.String | 1.3.6.X.1.0
Este recurso está disponível a partir da versão: 3.1.
|
- Parâmetros: X = Serial
- Retorno: string
- Descrição: Nome da EBS Modular
k3l.Config.EBS.X.GSMChannels | 1.3.6.X.2.0
Este recurso está disponível a partir da versão: 3.1.
|
- Parâmetros: X = Serial
- Retorno: int,int,...,int
- Descrição: Números dos canais GSM presentes no EBS Modular
k3l.Config.EBS.X.IP | 1.3.6.X.3.0
Este recurso está disponível a partir da versão: 3.3.
|
- Parâmetros: X = Serial
- Retorno: string
- Descrição: Endereço IP do EBS
Estado
k3l.Status.Link.X.Y.E1 | 1.4.1.X.Y.1.0
- Parâmetros: X = Serial, Y = Link
- Retorno: int (KE1Status)
- Descrição: Estado do link
k3l.Status.Link.X.Y.Z.E1 | 1.4.1.X.Y.Z.1.0
- Parâmetros: X = Serial, Y = Link, Z = Ignorado
- Retorno: int (KE1Status)
- Descrição: Estado do link
k3l.Status.Link.X.Y.Z.Channels | 1.4.1.X.Y.Z.2.0
- Parâmetros: X = Serial, Y = Link, Z = Canal
- Retorno: int (KE1ChannelStatus)
- Descrição: Estado do canal
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.
|
- Parâmetros: X = Serial, Y = Rx do link
- Retorno: int (KE1Status)
- Descrição: Retorna, separadamente, o estado dos Rx de um link de gravação passiva. No caso de uma E1HI 300 ou para o Link 0 de uma E1HI 600, passando '0' como parâmetro acessa-se o primeiro Rx e com '1', o segundo Rx. Para o Link 1 de uma E1HI 600, passa-se como parâmetro '2' para acessar o primeiro Rx e '3' para o segundo Rx.
k3l.Status.Channel.X.Y.CallStatus | 1.4.2.X.Y.1.0
- Parâmetros: X = Serial, Y = Canal
- Retorno: int (KCallStatus)
- Descrição: Estado da chamada
k3l.Status.Channel.X.Y.AudioStatus | 1.4.2.X.Y.2.0
- Parâmetros: X = Serial, Y = Canal
- Retorno: int (KDetectionTone)
- Descrição: Estado do áudio no canal
k3l.Status.Channel.X.Y.AddInfo | 1.4.2.X.Y.3.0
- Parâmetros: X = Serial, Y = Canal
- Retorno: int (K*ChannelStatus)
- Descrição: Informações adicionais sobre o estado do canal
k3l.Status.Channel.X.Y.EnabledFeatures | 1.4.2.X.Y.4.0
- Parâmetros: X = Serial, Y = Canal
- Retorno: int (KChannelFeatures)
- Descrição: Recursos habilitados
k3l.Status.Channel.X.TotalFail | 1.4.2.X.5.0
- Parâmetros: X = Serial
- Retorno: int
- Descrição: Total de canais em falha
k3l.Status.Channel.X.TotalIdle | 1.4.2.X.6.0
- Parâmetros: X = Serial
- Retorno: int
- Descrição: Total de canais em espera
k3l.Status.Channel.X.TotalCall | 1.4.2.X.7.0
- Parâmetros: X = Serial
- Retorno: int
- Descrição: Total de canais em chamada
k3l.Status.Channel.X.Y.DialNumber | 1.4.2.X.8.0
Este recurso está disponível a partir da versão: 3.2.
|
- Parâmetros: X = Serial, Y = Canal
- Retorno: int
- Descrição: Número discado na ligação corrente
k3l.Status.Channel.X.Y.CallDuration | 1.4.2.X.9.0
Este recurso está disponível a partir da versão: 3.2.
|
- Parâmetros: X = Serial, Y = Canal
- Retorno: int
- Descrição: Duração da ligação corrente em milissegundos
k3l.Status.Channel.X.Y.RecordingStatus | 1.4.2.X.10.0
Este recurso está disponível a partir da versão: 3.2.
|
- Parâmetros: X = Serial, Y = Canal
- Retorno: bool
- Descrição: Indica se o canal está gravando
k3l.Status.Channel.X.Y.AverageCallTime | 1.4.2.X.11.0
Este recurso está disponível a partir da versão: 3.3.
|
- Parâmetros: X = Serial, Y = Canal
- Retorno: int
- Descrição: Média da duração das ligações do canal, em milissegundos
k3l.Status.LinkErrorCounter.X.Y | 1.4.4.X.Y.0
- Parâmetros: X = Serial, Y = Link
- Retorno: int[16] (KLinkErrorCounter)
- Descrição: Contadore de erros do link
k3l.Status.GSMChannel.X.Y.SignalStrength.Z | 1.4.5.X.Y.1.Z.0
- Parâmetros: X = Serial, Y = Canal, Z = Ignorado
- Retorno: int [0 - 100]
- Retorno: 255 SIM CARD não registrado
- Descrição: Nível de sinal
k3l.Status.GSMChannel.X.Y.ErrorRate.Z | 1.4.5.X.Y.2.Z.0
- Parâmetros: X = Serial, Y = Canal, Z = Ignorado
- Retorno: int [0 - 7]
- Descrição: Taxa de erros
k3l.Status.GSMChannel.X.Y.RegistryStatus.Z | 1.4.5.X.Y.3.Z.0
- Parâmetros: X = Serial, Y = Canal, Z = Ignorado
- Retorno: int (KGsmRegistryStatus)
- Descrição: Estado do registro
k3l.Status.GSMChannel.X.Y.OperName.Z | 1.4.5.X.Y.4.Z.0
- Parâmetros: X = Serial, Y = Canal, Z = Ignorado
- Retorno: string
- Descrição: Nome da operadora
k3l.Status.GSMChannel.X.Y.UnreadSmsCount.Z | 1.4.5.X.Y.5.Z.0
- Parâmetros: X = Serial, Y = Canal, Z = Ignorado
- Retorno: int
- Descrição: Número de SMS não lidos
k3l.Status.GSMChannel.X.Y.EnabledFeatures.Z | 1.4.5.X.Y.6.Z.0
- Parâmetros: X = Serial, Y = Canal, Z = Ignorado
- Retorno: int
- Descrição: Recursos habilitados
k3l.Status.GSMChannel.X.Y.IMEI.Z | 1.4.5.X.Y.7.Z.0
- Parâmetros: X = Serial, Y = Canal, Z = Ignorado
- Retorno: string
- Descrição: Retorna o número IMEI (International Mobile Equipment Identity / Identificação Internacional de Equipamento Móvel).
k3l.Status.GSMChannel.X.Y.SIM.Z | 1.4.5.X.Y.8.Z.0
- Parâmetros: X = Serial, Y = Canal, Z = Ignorado
- Retorno: char
- Descrição: SIM card atualmente selecionado.
k3l.Status.GSMChannel.X.Y.CallStatus.Z | 1.4.5.X.Y.9.Z.0
- Parâmetros: X = Serial, Y = Canal, Z = Chamada
- Retorno: int,int,string,int (K3L_GSM_CALL_STATUS)
- Descrição: Estado da chamada Z no canal Y
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.
|
- Parâmetros: X = Serial, Y = Canal, Z = Ignorado
- Retorno: string
- Descrição: Retorna o número IMSI (International Mobile Subscriber Identity)
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.
|
- Parâmetros: X = Serial, Y = Canal, Z = Ignorado
- Retorno: string
- Descrição: Retorna o número ICCID (Integrated Circuit Card ID)
k3l.Status.Connected.X | 1.4.6.X.0
- Parâmetros: X = Serial
- Retorno: bool
- Descrição: Estado (1=conectado, 0=desconectado)
Estatística
k3l.ChannelStats.X.Y | 1.5.X.Y.0
VoIP
SIP
voip.GW.Profile.X.LocalAddress
- Parâmetros: X = SIP Profile id, retornado por EV_SIP_REGISTER_INFO
- Retorno: string
- Descrição: Endereço local utilizado para preencher as mensagens SIP.
voip.GW.Profile.X.LocalPort
- Parâmetros: X = SIP Profile id, retornado por EV_SIP_REGISTER_INFO
- Retorno: int
- Descrição: Porta local utilizada para preencher as mensagens SIP.
voip.GW.Profile.X.TransportType
- Parâmetros: X = SIP Profile id, retornado por EV_SIP_REGISTER_INFO
- Retorno: string
- Descrição: Tipo de transporte (UDP ou TCP) utilizado para preencher as mensagens SIP.
voip.GW.Profile.X.RTPAddress
- Parâmetros: X = SIP Profile id, retornado por EV_SIP_REGISTER_INFO
- Retorno: string
- Descrição: Endereço local utilizado para a troca de áudio RTP.
voip.GW.Profile.X.User
- Parâmetros: X = SIP Profile id, retornado por EV_SIP_REGISTER_INFO
- Retorno: string
- Descrição: "Address of Record" utilizado no registro.
voip.GW.Profile.X.AuthorizationUser
- Parâmetros: X = SIP Profile id, retornado por EV_SIP_REGISTER_INFO
- Retorno: string
- Descrição: Parâmetro "username" utilizado no campo "Authorization".
voip.GW.Profile.X.Realm
- Parâmetros: X = SIP Profile id, retornado por EV_SIP_REGISTER_INFO
- Retorno: string
- Descrição: Parâmetro "realm" utilizado no campo "Authorization".
voip.GW.Profile.X.Domain
- Parâmetros: X = SIP Profile id, retornado por EV_SIP_REGISTER_INFO
- Retorno: string
- Descrição: Endereço do servidor onde será feito o registro.
voip.GW.Profile.X.DomainPort
- Parâmetros: X = SIP Profile id, retornado por EV_SIP_REGISTER_INFO
- Retorno: int
- Descrição: Porta do servidor onde será feito o registro.
voip.GW.Profile.X.Proxy
- Parâmetros: X = SIP Profile id, retornado por EV_SIP_REGISTER_INFO
- Retorno: string
- Descrição: Endereço do proxy por onde a mensagem deve passar antes de chegar no servidor.
voip.GW.Profile.X.ProxyPort
- Parâmetros: X = SIP Profile id, retornado por EV_SIP_REGISTER_INFO
- Retorno: int
- Descrição: Porta do proxy por onde a mensagem deve passar antes de chegar no servidor.
voip.GW.Profile.X.Registered
- Parâmetros: X = SIP Profile id, retornado por EV_SIP_REGISTER_INFO
- Retorno: string
- Descrição: Indica se o profile está registrado ou não em um servidor.
RTP
voip.Media.RTPStatus.X.Transmit.LastSequenceNumber
- Parâmetros: X = Canal SIP em chamada
- Retorno: int
- Descrição: Número de sequência do último pacote RTP enviado.
voip.Media.RTPStatus.X.Transmit.PacketCount
- Parâmetros: X = Canal SIP em chamada
- Retorno: int
- Descrição: Número de pacotes RTP enviados.
voip.Media.RTPStatus.X.Transmit.OctetCount
- Parâmetros: X = Canal SIP em chamada
- Retorno: int
- Descrição: Número total de octetos RTP enviados.
voip.Media.RTPStatus.X.Transmit.PacketLost
- Parâmetros: X = Canal SIP em chamada
- Retorno: int
- Descrição: Número de pacotes RTP enviados perdidos.
voip.Media.RTPStatus.X.Receive.InitialSequenceNumber
- Parâmetros: X = Canal SIP em chamada
- Retorno: int
- Descrição: Número de sequência do primeiro pacote RTP recebido.
voip.Media.RTPStatus.X.Receive.LastSequenceNumber
- Parâmetros: X = Canal SIP em chamada
- Retorno: int
- Descrição: Número de sequência do último pacote RTP recebido.
voip.Media.RTPStatus.X.Receive.PacketCount
- Parâmetros: X = Canal SIP em chamada
- Retorno: int
- Descrição: Número de pacotes RTP recebidos.
voip.Media.RTPStatus.X.Receive.DroppedCount
- Parâmetros: X = Canal SIP em chamada
- Retorno: int
- Descrição: Quantidade total de pacotes entrantes perdidos.
voip.Media.RTPStatus.X.Receive.LastDroppedCount
- Parâmetros: X = Canal SIP em chamada
- Retorno: int
- Descrição: Quantidade de pacotes entrantes perdidos em sequência. Ao receber um pacote com o número de sequência esperado, este contador é zerado.
Comandos Disponíveis
k3l.ResetLink.X.Y
- Parâmetros: X = Serial, Y = Link
- Descrição: Reinicia o link
k3l.ClearLinkErrorCounter.X.Y
- Parâmetros: X = Serial, Y = Link
- Descrição: Zera os contadores de erro do link
k3l.BlockLink.X.Y
- Parâmetros: X = Serial, Y = Link
- Descrição: Bloqueia todos os canais do link
k3l.ResetModem.X.Y
Este recurso está disponível a partir da versão: 3.3.
|
- Parâmetros: X = Serial, Y = Canal
- Descrição: Reinicia o modem
k3l.ClearChannelStats.X.Y
Este recurso está disponível a partir da versão: 3.3.
|
- Parâmetros: X = Serial, Y = Canal
- Descrição: Zera as estatísticas do canal
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:
- 'khomp' representa a comunidade (ao invés de 'public'),
- 'localhost' indica em qual máquina o KQueryServer está rodando (pode também ser utilizado um IP, caso não seja na mesma máquina),
- '14161' é a porta aonde o KQueryServer por padrão esperará requisições SNMP (a porta 14130 continuará funcionando para as requisições originais do KQueryServer) e
- '.1.3.6.1.4.1.32624' é a OID base que representa a Khomp na IANA (Internet Assigned Numbers Authority).
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).