Diff: sip.h

Revision:

69:65665afbad5d

Parent:

48:195c97f12e8e

Child:

72:895ca792c647

--- a/sip.h	Fri Nov 07 17:57:55 2014 +0000
+++ b/sip.h	Wed Nov 12 13:25:54 2014 +0000
@@ -1,3 +1,11 @@
+/**
+ * @file sip.h
+ * @Synopsis Implementa as funções utilizadas no tratamento SIP entre a Header e o server
+ * @author Jhonatan Casale
+ * @version 1
+ * @date 2014-11-05
+ * \class Sip
+ */
 #ifndef __SIP_H__
 #define __SIP_H__
 
@@ -12,12 +20,18 @@
 #include "configs.h"
 
 #define __INVITE_MAX_WAITING_TIME__ 30
+///< Indica o timeout de espera de resposta de pedido de ligação para o servidor, após esse tempo responde ligação encerrado para o Call_box
 #define SIP_MAXFIELDSIZE 256
+///< Define o tamanho máximo de algumas mensagens usadas na negociação Sip.
 #define SIP_MAXMSGSIZE 2048
+///< Define o tamanho máximo das mensagens enviadas, porém, fora de uso atualmente.
 #define SIP_REGISTER_EXPIRES 120
+///< Define o timeout do registro no servidor asterisk ( * ), porém, hardcoded atualmente.
 #define DRAMBASEADDR    0xa0000000
+///< Indica o inicio do bloco DRAM, porém, fora de uso atualmente.
 #define SIP_ALLOW "Allow: ACK, BYE, CANCEL, INFO, INVITE, NOTIFY, OPTIONS, REFER"
 /* #define SIP_ALLOW "Allow: ACK, BYE, CANCEL, INVITE, OPTIONS" */
+///< String de composição de pacotes enviados pela Header para o *
 
 #define sip_idle 0
 #define sip_waiting_trying 1 << 1
@@ -51,53 +65,486 @@
     void __end_sock__( void );
     void __reconnect__( void );
 public :
-    uint8_t status;
+    uint8_t status; ///< Representa o status do objeto Sip em dado momento.
+
+        /**
+         * @Synopsis Cria um objeto Sip setando ramal e porta e o restando buscando valores default.
+         *
+         * @param id O identificador do objeto ( por definição de projeto o ramal ( ext ) ).
+         * @param my_port A porta do objeto Sip para comunicação com o servidor.
+         *
+         * Exemplo:
+         *
+         * @code
+         * ...
+         *  Sip * sip = new Sip( 5002, 5002 );
+         * ...
+         * @endcode
+         */
     Sip( int id, uint16_t my_port );
+
+        /**
+         * @Synopsis Cria um objeto Sip setando todos os parametros passados.
+         *
+         * @param server_ip O endereço IP do servidor para o qual será encaminhado pedidos de ligação, registro, etc.
+         * @param server_port A porta deste servidor para o qual os pacotes eth serão encaminhados.
+         * @param my_ip O endereço IP do objeto Sip para tratativa com o server.
+         * @param my_port A porta do objeto Sip para recebimento de pacotes.
+         * @param my_ext O identificador do objeto ( por definição de projeto o ramal ( ext ) ).
+         * @param peer_ext O ramal do servidor, para onde os pedidos de chamada serão solicitados.
+         * @param id O identificador único do objeto Sip, que por convenção, deve ser o mesmo que o ramal.
+         *
+         * Exemplo:
+         *
+         * @code
+         *  Sip * sip = new Sip( "192.168.120.200", 5075, "192.168.120.171", 812, 851, 913, 851 );
+         * @endcode
+         */
     Sip( char * server_ip, int server_port, char * my_ip, int my_port, int my_ext, int peer_ext, int id );
+
+        /**
+         * @Synopsis Destroi o objeto Sip
+         *
+         * Exemplo:
+         *
+         * @code
+         * ...
+         *  delete( sip );
+         * ...
+         * @endcode
+         */
     ~Sip();
+
+        /**
+         * @Synopsis Responsavel por montar encaminhar o pacote de registro para o servidor.
+         *
+         * Exemplo:
+         * @code
+         * ...
+         *  sip->registry();
+         * ...
+         * @endcode
+         */
     void registry( void );
+
+        /**
+         * @Synopsis Efetivamente envia o pedido de ligação para o servidor.
+         *
+         * @return Uma referência para uma ligação, caso a negociação resulte na aceitação por parte do servidor, NULL, caso contrário.
+         * \note Como por conveniência, foi configurado no servidor * que existiria musica de conforto, o que fez com que, assim que é 
+         * feito o envio do pacote de invite, uma chamada é criada para se trocar os dados desse audio de conforto, ficando a Header na
+         * espera do servidor aceitar ou não o pedido de forma definitiva, no caso em que o server dizer "ok", a mesma chamada é retornada,
+         * porém, no caso de timeout ou negativa do server, a chamada é destruida e NULL é retornado.
+         *
+         * Exemplo:
+         * @code
+         * ...
+         *  VZ_call * call = sip->invite();
+         * ...
+         * @endcode
+         */
     VZ_call * invite( void );
     
+        /**
+         * @Synopsis Monta o pacote para ser encaminhado para o servidor.
+         *
+         * @param header O pré-pacote contendo o cabeçalho do pacote.
+         * @param body O pré-pacote contendo o corpo do pacote.
+         * @param pkg Um ponteiro para o pacote montado no formado header + "Content-Length: " + strlen( body ) + body;
+         *
+         * @return O pacote montado, o mesmo endereço apontado por pkg.
+         *
+         * Exemplo:
+         * @code
+         * ...
+         *  #define SIP_MAXMSGSIZE 2048;
+         *  char pkg[ SIP_MAXMSGSIZE ];
+         *  char header[ SIP_MAXMSGSIZE ];
+         *  char bod y[ SIP_MAXMSGSIZE ];
+         *  pkg = sip->make_content_length( header,body, pkg ); 
+         * ...
+         * @endcode
+         */
     char * make_content_length( char * header, char * body, char * pkg );
-    
+
+        /**
+         * @Synopsis Função que decodifiica o codigo recebido em um dado pocote Sip.
+         *
+         * @param s O pacote que se deseja decodificar.
+         *
+         * @return O código identificado no pacote recebido.
+         * 
+         * \note Não esta em uso atualmente.
+         *
+         * Exemplo:
+         * @code
+         * ...
+         *  char buffer[ 1024 ];
+         *  //assumindo que em buffer será armazenado o valor do pacote que será analisado para saber o codigo de retorno.
+         *  int code = sip->get_return_code( buffer );
+         * ...
+         * @endcode
+         */
     int get_return_code( char * s );
+
+        /**
+         * @Synopsis Gera um nro de cseq para preenchimento no cabeçalho dos pacotes Sip.
+         *
+         * @return O numero gerado.
+         *
+         * Exemplo:
+         * @code
+         * ...
+         *  int cseq = sip->get_cseq();
+         * ...
+         * @endcode
+         */
     int get_cseq( void );
+
+        /**
+         * @Synopsis Obtem o id( ramal ) do objeto.
+         *
+         * @return Retorna o id( ramal ) do objeto.
+         *
+         * Exemplo:
+         * @code
+         * ...
+         *  int ext = sip->get_id();
+         * ...
+         * @endcode
+         */
     int get_id( void );
-    int get_my_rtp_port( void );
     
+        /**
+         * @Synopsis Obtem a porta rtp na qual a Header ira encaminhar e receber dados do Server.
+         *
+         * @return O numero da porta RTP usado pelo objeto Sip durante uma determinada chamada.
+         *
+         * Exemplo:
+         * @code
+         * ...
+         *  int rtp_port = sip->get_my_rtp_port();
+         * ...
+         * @endcode
+         */
+        int get_my_rtp_port( void );
+    
+        /**
+         * @Synopsis Efetivamente cria o pacote de registro.
+         *
+         * @param buffer Recebe um ponteiro para uma região de memória onde irá escrever o pacote de registro.
+         *
+         * @return Um ponteiro para o inicio do pacote montado ( mesmo endereço passado como parâmetro ).
+         */
     char * build_registry_package( char * buffer );
-    char * build_unregistry_package( char * buffer );
-    char * build_invite_package( char * s, char * callbox_string, int * cseq );
-    char * build_bye_package( char * buffer );
-    char * build_ack_package( char * buffer, unsigned char * orig );
-    char * build_generic_reply_package(char * s, unsigned char * orig, char * tag);
-    char * build_trying_package( char * buffer, unsigned char * orig );
-    char * build_busy_package( char * buffer, unsigned char * orig );
-    char * build_reply_package( char * buffer, unsigned char * orig );
-        
+    
+        /**
+         * @Synopsis Efetivamente cria um pacote para desregistrar o objeto no server.
+         *
+         * @param buffer Recebe um ponteiro para uma região de memória onde irá escrever o pacote de desregistro.
+         *
+         * @return Um ponteiro para o inicio do pacote montado ( mesmo endereço passado como parâmetro ).
+         */
+        char * build_unregistry_package( char * buffer );
+    
+        /**
+         * @Synopsis Efetivamente cria um pacote de invite ( pedido de chamada ) do Call_box para o server.
+         *
+         * @param s Um ponteiro para uma região de memória onde irá escrever o pacote de invite.
+         * @param callbox_string Uma string de identifcação do Call_box.
+         * @param cseq O nro de cseq que irá ser colocado no pacote.
+         *
+         * @return 
+         */
+        char * build_invite_package( char * s, char * callbox_string, int * cseq );
+    
+        /**
+         * @Synopsis Efetivamente cria um pacote de "despedida" para o servidor, usado para encerrar ligações.
+         *
+         * @param buffer Um ponteiro para uma região de memória onde irá escrever o pacote de bye.
+         *
+         * @return Um ponteiro para o inicio do pacote montado ( mesmo endereço passado como parâmetro ).
+         */
+        char * build_bye_package( char * buffer );
+    
+        /**
+         * @Synopsis Efetivamente cria um pacote de ack de mensagem recebida.
+         *
+         * @param buffer Um ponteiro para a posição de memória onde será criado o pacote ack
+         * @param orig O pacote original recebido do servidor, serve como referência na criação do pacote de resposta,
+         *
+         * @return Um ponteiro para o inicio do pacote montado ( mesmo endereço passado como parâmetro ).
+         */
+        char * build_ack_package( char * buffer, unsigned char * orig );
+    
+        /**
+         * @Synopsis 
+         *
+         * @param s Um ponteiro para a posição de memória onde será montado o pacote.
+         * @param orig O pacote recebido do servidor, serve como referência para criação da resposta.
+         * @param tag A tag que será usada no pacote de resposta.
+         *
+         * @return Um ponteiro para o inicio do pacote montado ( mesmo endereço passado como parâmetro ).
+         */
+        char * build_generic_reply_package( char * s, unsigned char * orig, char * tag );
+    
+        /**
+         * @Synopsis Cria um pacote genérico de resposta.
+         *
+         * @param buffer Um ponteiro para a posição de memória onde será montado o pacote.
+         * @param orig 
+         *
+         * @return Um ponteiro para o inicio do pacote montado ( mesmo endereço passado como parâmetro ).
+         */
+        char * build_trying_package( char * buffer, unsigned char * orig );
+    
+        /**
+         * @Synopsis 
+         *
+         * @param buffer Um ponteiro para a posição de memória onde será montado o pacote.
+         * @param orig O pacote de origem, serve como referência na criação do pacote.
+         *
+         * @return Um ponteiro para o inicio do pacote montado ( mesmo endereço passado como parâmetro ).
+         */
+        char * build_busy_package( char * buffer, unsigned char * orig );
+    
+        /**
+         * @Synopsis 
+         * 
+         * @param buffer Um ponteiro para a posição de memória onde será montado o pacote.
+         * @param orig O pacote de origem, serve como referência na criação do pacote.
+         *
+         * @return Um ponteiro para o inicio do pacote montado ( mesmo endereço passado como parâmetro ).
+         */
+        char * build_reply_package( char * buffer, unsigned char * orig );
+    
+        /**
+         * @Synopsis Preenche de forma aleatótia 16 posições de memória.
+         *
+         * @param buffer Um ponteiro que aponta para o inicio das 16 ( bytes ) posições que serão preenchidas.
+         *
+         * @return Retorna um ponteiro para os dados preenchidos ( mesmo endereço passado como parâmetro.
+         */
     char * fill_random16h(char * buffer );
-    char * fill_random( char * buffer, int size );
-    int fill_random_rtp_port( void );
+    
+        /**
+         * @Synopsis Preenche de forma aleatótia dados.
+         *
+         * @param buffer Um ponteiro que aponta para o inicio das posições a serem preenchidas.
+         * @param size A quantidade ( em posições ) que serão preenchidas.
+         *
+         * @return Um ponteiro para o inicio das posições preenchidas ( mesmo endereço do parâmetro passado ).
+         */
+        char * fill_random( char * buffer, int size );
+    
+        /**
+         * @Synopsis Gera aleatóriamente a porta RTP de onde os dados de audiao serão enviados da Header.
+         *
+         * @return O nro da porta que será usada na negociação Sip.
+         */
+        int fill_random_rtp_port( void );
     
+        /**
+         * @Synopsis Dado um pacote recebido do server, decodifica o nro cseq.
+         *
+         * @param package O pacote do qual se tem interesse em decodificar.
+         * @param cseq Um ponteiro que aponta para a posição de memória onde será escrito o cseq.
+         *
+         * @return Um ponteiro para o inicio da posição de memória que contem o cseq ( mesma passada como parâmetro ).
+         */
     char * decode_cseq(unsigned char * package, char * cseq);
-    char * decode_branch( unsigned char * package, char * branch );
-    int decode_gettag( unsigned char * package, char * tag, char * out );
+    
+        /**
+         * @Synopsis Dado um pacote recebido do server, decodifica o branch.
+         *
+         * @param package Um ponteiro para o pacote recebido do servidor o qual temos interesse em decodificar.
+         * @param branch Um ponteiro para o inicio da posição de memória onde escreveremos o branch
+         *
+         * @return Um ponteiro para o inicio da posição de memória onde escrevemos o branch ( mesma passada como parâmentro ).
+         */
+        char * decode_branch( unsigned char * package, char * branch );
+    
+        /**
+         * @Synopsis Busca por uma determinado substring em um pacote recebido do servidor. Copiando o restando desse pacote para
+         * uma posição de interesse.
+         *
+         * @param package O pacote que se tem interesse em decodificar.
+         * @param tag A substring que a função ira buscar em package.
+         * @param out A região de memória para onde o restante dos dados contidos em package será copiado, caso a substring seja 
+         * encontrada.
+         *
+         * @return 1, caso tenha encontrado a string tag contida no package, copia o restando do conteudo de package para out e retorna 1,
+         * retorna 0 caso a substring não seja encontrada.
+         */
+        int decode_gettag( unsigned char * package, char * tag, char * out );
+    
+        /**
+         * @Synopsis Esta função deveria mudar a conexão com o servidor, caso o mesmo caia. Porém, não em uso.
+         */
+    void change_sip_server();
     
-    void change_sip_server();
-    char * get_next_server_ip( char *server_ip );
-    int get_next_server_port();
-    int get_next_server_ext();
+        /**
+         * @Synopsis Obtém o nro de IP do servidor que irá sediar os pedidos de ligações e demais tratamentos, em caso do primeiro 
+         * server vir a cair, porém, função não em uso.
+         *
+         * @param server_ip Um ponteiro que aponta para a posição de memória onde será escrito o valor do IP do servidor.
+         *
+         * @return Um ponteiro para o inicio do endereço IP do server ( mesmo passado como parametro )
+         *
+         * Exemplo:
+         * @code
+         * ...
+         *  char new_ip[ 16 ];
+         *  strcpy( new_ip, sip->get_next_server_ip() );
+         * ...
+         * @endcode
+         */
+        char * get_next_server_ip( char *server_ip );
+    
+        /**
+         * @Synopsis Obtém o nro de IP do servidor que irá sediar os pedidos de ligações e demais tratamentos, em caso do primeiro
+         * server vir a cair. Porém, função não em uso. 
+         *
+         * @return O nro da porta de comunicação com o próximo server.
+         *
+         * Exemplo:
+         * @code
+         * ...
+         *  int port = sip->get_next_server_port();
+         * ...
+         * @endcode
+         */
+        int get_next_server_port();
+
+
+        /**
+         * @Synopsis Obtém o nro do ramal de comunicação com o proximo servidor Sip, nos casos em que o primeiro servidor passar por
+         * instabilidade, atualmente, não em uso.
+         *
+         * @return O valor do ramal de comunicação com o promixo servidor.
+         *
+         * Exemplo:
+         * @code
+         * ...
+         *  int next_server_ext = sip->get_next_server_ext();
+         * ...
+         * @endcode
+         */
+        int get_next_server_ext();
     
-    void set_server_ext( int new_server_ext );
-    void set_server_port( int new_server_port );
-    void set_ext( int ext );
-    void set_port( int port );
-    void set_server_ip( char * new_server_ip );
+        /**
+         * @Synopsis Recebe um ramal de comunicação com o servidor, realizando solicitações futuras com esse ramal.
+         *
+         * @param new_server_ext O Ramal do servidor que será associado ao objeto Sip
+         *
+         * Exemplo:
+         * @code
+         * ...
+         *  sip->set_server_ext( 913 );
+         * ...
+         * @endcode
+         */
+        void set_server_ext( int new_server_ext );
+    
+        /**
+         * @Synopsis Recebe uma porta de comunicação com o servidor, setando e realizando comunicaões entre Header-Server atraves 
+         * dessa porta
+         *
+         * @param new_server_port A porta do servidor que será associada ao objeto Sip
+         *
+         * Exemplo:
+         * @code
+         * ...
+         *  sip->set_server_port( 818 );
+         * ...
+         * @endcode
+         */
+        void set_server_port( int new_server_port );
+    
+        /**
+         * @Synopsis Seta ramal de comunicação Sip da Header.
+         *
+         * @param ext Ramal que será associado ao objeto Sip criado.
+         *
+         * Exemplo:
+         * @code
+         * ...
+         *  sip->set_ext( 818 );
+         * ...
+         * @endcode
+         *
+         */
+        void set_ext( int ext );
     
-    int listen_SIP_server( void );
-    void send_bye( void );
-    void send_unregistry_pkg( void );
+        /**
+         * @Synopsis Seta a porta de comunicação Sip da Header.
+         *
+         * @param port Porta que será associada ao objeto Sip criado.
+         *
+         * Exemplo:
+         * @code
+         * ...
+         *  sipset_port( 1028 );
+         * ...
+         * @endcode
+         *
+         *
+         */
+        void set_port( int port );
+    
+        /**
+         * @Synopsis Seta o valor passado como parâmetro como sendo o endeço IP de contato do servidor.
+         *
+         * @param new_server_ip O endereço que será associado ao objeto Sip.
+         *
+         * Exemplo:
+         * @code
+         * ...
+         *  sip->set_server_ip( "192.168.120.8" );
+         * ...
+         * @endcode
+         */
+        void set_server_ip( char * new_server_ip );
     
-    uint8_t get_status( void );
+        /**
+         * @Synopsis Responsavel por ouvir o servidor *, verificando se o mesmo esta mandando alguma mensagem, seja Sip ou qualquer outra
+         * nas portas acordadas.
+         *
+         * @return 0, sucesso na execução, sem pendencia, ou retorna um nro maior que zero, representando o nro do ramal cuja ligação deve
+         * ser encerrada.
+         */
+        int listen_SIP_server( void );
+    
+        /**
+         * @Synopsis Envia efetivamente o pacote de despedita com Call_box pro servidor
+         *
+         * Exemplo:
+         * @code
+         * ...
+         *  sip->send_bye();
+         * ...
+         * @endcode
+         */
+        void send_bye( void );
+    
+        /**
+         * @Synopsis Esta função Envia efetivamente o pacote de "desregistro" para o servidor.
+         * 
+         * Exemplo:
+         * @code
+         * ...
+         *  sip->send_unregistry_pkg();
+         * ...
+         * @endcode
+         *
+         */
+        void send_unregistry_pkg( void );
+    
+        /**
+         * @Synopsis 
+         *
+         * @return 
+         */
+        uint8_t get_status( void );
 };
 #endif
\ No newline at end of file