Diff: utils.h

Revision:

69:65665afbad5d

Parent:

68:b54993674190

Child:

70:714c33487aae

--- a/utils.h	Fri Nov 07 17:57:55 2014 +0000
+++ b/utils.h	Wed Nov 12 13:25:54 2014 +0000
@@ -1,3 +1,11 @@
+/**
+ * @file utils.h
+ * @Synopsis Funções de propósito geral são encontradas nesse arquivo. 
+ * @author Jhonatan Casale
+ * @version 1
+ * @date 2014-11-06
+ */
+
 #ifndef __UTILS_H__
 #define __UTILS_H__
 
@@ -13,12 +21,11 @@
 #include "call_box.h"
 #include "timeslice.h"
 #include "parallelcpld.h"
-#include "test.h"
 #include "prompt.h"
 #include "configs.h"
 
-/* Armazena o ultimo pacote enviado para os CBx */
 extern uint8_t cb_tx_buffer[ __CB_BUFFER_SIZE__ ];
+///< Armazena o ultimo pacote enviado para os CBx
 
 using namespace std;
 
@@ -36,21 +43,243 @@
   else if( debug_sip ) debug_msg("Paramento sip null"); \
 }
 
+/**
+ * @Synopsis Transpões os elementos de um vetor, invertendo a ordendo em que os mesmos aparecem.
+ *
+ * @param str[] Um ponteiro para o inicio da string que desejamos inverter os elementos de posição
+ * @param length O numero de elementos que queremos trocar.
+ *
+ * Exemplo:
+ * @code
+ * ...
+ *  char str[ 256 ] = "This is a only test";
+ *  reverse( str, strlen( str ) );
+ * ...
+ * @endcode
+ */
 void reverse( char str[], int length );
+
+/**
+ * @Synopsis Implementa a funcionalidade de, dado um numero em uma base, converte o mesmo para seu equivalente em string.
+ *
+ * @param num O numero que se deseja converter em string.
+ * @param str Um ponteiro para o inicio da região de memória onde será montado a string.
+ * @param base A base de conversão adotada.
+ *
+ * @return Um ponteiro para o primeiro elemento da string montada.
+ *
+ * Exemplo:
+ * @code
+ * ...
+ *  int tmp = 119;
+ *  char buffer[ 16 ];
+ *  buffer = itoa( tmp, buffer, 10 );
+ * ...
+ * @endcode
+ */
 char* itoa(int num, char* str, int base);
+
+/**
+ * @Synopsis Função responsavel por apagar todos os leds em uso da Header.
+ *
+ * Exemplo:
+ * @code
+ * ...
+ *  reset_leds();
+ * ...
+ * @endcode
+ */
 void reset_leds( void );
+
+/**
+ * @Synopsis Responsavel por inicializar as configurações iniciais de conexão eth
+ *
+ * @return 0 ( zero ) caso tenha uma execução bem sucedida, um numero negativo, caso contrário.
+ *
+ * Exemplo:
+ * @code
+ * ...
+ *   int eth_status = __init_eth__();
+ * ...
+ * @endcode
+ */
 int __init_eth__( void );
 
+/**
+ * @Synopsis Busca por um determinado Call_box no vetor de Call_box usando como chave de busca o ramal.
+ *
+ * @param v_cb O vetor contendo todos os Call_box conhecidos pela Header em determinado momento.
+ * @param ext O ramal pelo qual se irá buscar o CBx.
+ *
+ * @return NULL caso não tenha sido encontrado nenhum CBx com esse ramal; retorna um ponteiro para o Call_box que possui esse ramal,
+ * caso o mesmo tenha sido encontrado.
+ *
+ * Exemplo:
+ * @code
+ * ...
+ *  Vector * v_cb = new Vector();
+ *      //assumindo que esse vetor de Call_Box já foi populado.
+ *  int ext = 5218;
+ *  Call_Box * cb = __find_CB__( v_cb, ext );
+ * ...
+ * @endcode
+ */
 Call_Box * __find_CB__( Vector * v_cb, int ext );
+
+/**
+ * @Synopsis Busca por uma determinada ligação vz_call no vetor de v_calusando como chave de busca o ramal.
+ *
+ * @param v_call Um vetor contendo todas as vz_calls em andamento em um dado momento.
+ * @param ext O ramal pelo qual se irá buscar a vz_call.
+ *
+ * @return NULL, caso essa chamada não tenha sido encontrada; um ponteiro para esta chamada, caso a mesma tenha sido encontrada.
+ *
+ * Exemplo:
+ * @code
+ * ...
+ *  Vector * v_call = new Vector();
+ *      //assumindo que esse vetor de VZ_call já foi populado.
+ *  int ext = 5218;
+ *  VZ_call * call = __find_Call__( v_call, ext );
+ * ...
+ * @endcode
+ */
 VZ_call * __find_Call__( Vector * v_call, int ext );
+
+/**
+ * @Synopsis Função responsavel por "envelhecer" os registros na Header, na prática, é essa função que pergunta de tempo
+ * em tempo se o CBx ainda continua ativo; Essa função também é responsavel por remover o CBx do v_cb assim como deletar o elemento cb
+ * assossiado.
+ *
+ * @param v_cb Um vetor contendo todos os Call_box conhecidos pela Header em um determinado momento.
+ * @param data Usado para a criação do pacote de "ping" que a Header irá enviar para o CBx.
+ * @param write_buffer Local de memória onde efetivamente irá ser montado o pacote para envio ao CBx do pacote de "ping" ( Registry ).
+ *
+ * Exemplo:
+ * @code
+ * ...
+ *  Vector * v_cb = new Vector();
+ *      //assumindo que esse vetor de Call_Box já foi populado.
+ *  uint8_t buffer[ 300 ];
+ *      uint8_t write_buffer[ 300 ];
+ *  registry_aging( v_cb, buffer, write_buffer );
+ * ...
+ * @endcode
+ */
 void registry_aging( Vector * v_cb, uint8_t * data, uint8_t * write_buffer );
-int sip_manager( Vector * v_cb, Vector * v_call, uint8_t * write_buffer );
+
+/**
+ * @Synopsis Responsavel por escutar a porta de conexão com o servidor, verificando se o mesmo mandou algum dado.
+ *
+ * @param v_cb Um vetor contendo todos os Call_box conhecidos pela Header em um determinado momento.
+ * @param v_call Um vetor contendo todas as vz_calls em andamento em um dado momento.
+ *
+ * @return 0 ( zero ) se tudo correu bem, um numero menor do que zero, caso algum problema tenha acontecido na execusão, e um numero
+ * maior que zero indicando o ramal que deve ser removido do vetor de ligações.
+ *
+ * Exemplo:
+ * @code
+ * ...
+ *  Vector * v_cb = new Vector();
+ *  Vector * v_call = new Vector();
+ *      // assumindo que os vetores já foram populados.
+ *  int ret = sip_manager( v_cb, v_call );                                                                  
+ *  if( ret > 0x00 ){
+ *          // tratar esse request
+ *  }          
+ * ...
+ * @endcode
+ */
+int sip_manager( Vector * v_cb, Vector * v_call ); 
+
+/**
+ * @Synopsis Responsável por remover calls por timeout.
+ *
+ * @param v_call Um vetor contendo todas as vz_calls em andamento em um dado momento.
+ * @param v_cb Um vetor contendo todos os Call_box conhecidos pela Header em um determinado momento.
+ * @param data Usado para a criação do pacote de "ping" que a Header irá enviar para o CBx.
+ * @param write_buffer Local de memória onde efetivamente irá ser montado o pacote para envio ao CBx. 
+ * @param ts O timeslice que será possivelmente devolvido.
+ *
+ * Exemplo:
+ * @code
+ * ...
+ *  Vector * v_call = new Vector();
+ *  Vector * v_cb = new Vector();
+ *      // assumindo que os vetores já foram populados.
+ *  uint8_t buffer[ 300 ];
+ *      uint8_t write_buffer[ 300 ];
+ *      Timeslice * ts = new Timeslice();
+ *      ...
+ *      call_manager( v_call, v_cb, buffer, write_buffer, ts ); 
+ * ...
+ * @endcode
+ */
 void call_manager( Vector * v_call, Vector * v_cb, uint8_t * data, uint8_t * write_buffer, Timeslice * ts );
+
+/**
+ * @Synopsis Responsavel por formatar e enviar o pacote de telemetria para o servidor de interesse.
+ *
+ * @param ext Ramal do CBx emissor do pacote de telemetria.
+ * @param port Porta do CBx emissor do pacote de telemetria.
+ * @param data Vetor contendo os dados de telemetria em si.
+ *
+ * Exemplo:
+ * @code
+ * ...
+ *  ext = 5160;
+ *  port = 5060;
+ *  //assumindo que data_from_cb contém os dados vindos do Call_box.
+ *  build_telemetry_report( ext, port, ( char * )data_from_cb );
+ * ...
+ * @endcode
+ */
 void build_telemetry_report( int ext, int port, char * data );
+
+/**
+ * @Synopsis Executa chamada para chamada de baixo nivel send2callboxes para efetivamente enviar os dados para o CBx.
+ *
+ * @param buffer O pacote VZ que será enviado para os CBx.
+ *
+ * Exemplo:
+ * @code
+ * ...
+ * //assumindo que o pacote já foi montado em pkg.
+ *  __send_to_cb__( pkg );
+ * ...
+ * @endcode
+ */
 void __send_to_cb__( uint8_t * buffer );
+
+/**
+ * @Synopsis Função usada na ordenação dos CBx para exibição no comando "ls"
+ *
+ * @param a O primeiro ramal que se quer comparar.
+ * @param b O segundo ramal que se quer comparar.
+ *
+ * @return 0 ( zero ) se os valores forem iguais, maior que zero, se o primeiro valor ser maior que o segundo e retorna um numero
+ * negativo, caso o segundo valor seja maior que o primeiro.
+ *
+ * Exemplo:
+ * @code
+ * ...
+ *  int a = 10;
+ *  int b = 119;
+ *  int result = ls_comp( ( const void * )&a, ( const void * )&b );
+ * ...
+ * @endcode
+ */
 int ls_comp( const void * a, const void * b );
 
+/**
+ * @Synopsis Efetivamente inicializa a conexão UDP com o server.
+ */
 void init_telemetry_handler( void );
+
+
+/**
+ * @Synopsis Fecha e abre novamente a conexão UDP com o server 
+ */
 void re_start_telemetry( void );
 
 #endif
\ No newline at end of file