ami_c/README.md

<h1 align="center">*Biblioteca AMI_C*</h1>
<p align="left">
</p>


#### Estrutura da biblioteca visível

Estrutura dos argumentos que recebe das actions e eventos
```c
typedef struct s_ami_args {
	char *key; // chave do argumento 
	char *value; // value do argumento 
	struct s_ami_args *next;
} ARGS;
```

------------

Estrutura de respostas das actions
```c
typedef struct s_ami_response {
	char *response; // valor da chave response no bloco 
	ARGS *args; // argumentos do bloco response 
	int count; // quantidade de argumentos */
} RESPONSE;
```

------------

Estrutura dos eventos
```c
typedef struct s_ami_event{
	char *event; // nome do evento 
	ARGS *args; // argumentos do evento 
	int count; // constagem do event. decrescente 1000 - 0   
	struct s_ami_event *next;
} EVENT;
```

------------

Estrutura do retorno das action
```c
typedef struct s_ami_action{
	RESPONSE *response;
	char *actionid;
	EVENT *events;
	struct s_ami_action *next;
} ACTION;
```

------------

Estrutura dos argumentos para mandar action
```c
struct ss_args {
	char key[MAX_LEN_KEY_ACTION];
	char value[MAX_LEN_VALUE_ACTION];
};
```

------------

Estrutura das actions que será enviada
```c
struct ss_action {
	char name_action[MAX_LEN_NAME_ACTION];
	int count_args;
	struct ss_args *args;
};
```

#### Função da API da biblioteca:

Primeira função que deverá ser chamada. Essa função inicializa a estrutura necessária.\n
* warning Não deve ser liberada diretamente esse ponteiro. Use a função close_ami.
* return retorna NULL caso tenha erro

`AMI *ami_init();`

------------


Essa função encerrará essa instância com ami. A memória será liberada dessa instância
* return sucesso 0, falha -1

`int ami_close(AMI  *ami);`

------------


A conexão com a AMI e algumas informações serão refeitas
* return sucesso 0, falha -1

`int ami_restart(AMI *ami);`

------------


Defini as credenciais necessárias para fazer login com a ami
* param username manager
* param password manager (secret)
* return sucesso 0, falha -1

`int ami_set_credentials( AMI *ami, const char *username, const char *password );`

------------


defini o caminho para conectar ao ami
* param address ip
* param port valor 0 defini porta padrão automaticamente
* return sucesso 0, falha -1

`int ami_set_net( AMI *ami, const char *address, int port );`

------------


Começa o processo de conexão, obter informação e receber dados do ami
* return sucesso 0, falha -1

`int ami_c (AMI *ami );`

------------


Retorna o socket dessa instância que está sendo usado
* return socket(int)

`int ami_get_socket(AMI *ami);`

------------


Está connectado ao ami do asterisk.\n
Caso não esteja conectado, a biblioteca continuará tentando conectar. A biblioteca só irá parar  de tentar conectar com a função close_ami.
* return connectado 1, falha 0

`int ami_is_connected(AMI *ami);`

------------


Verifica se a comunicação está com login sucesso. Retorna 0 a biblioteca tentará fazer o mesmo login. Para parar as tentativas use função close_ami.
* return sucesso 1, falha 0

`int ami_is_logged(AMI *ami);`

------------


Envia a action que está na struct ss_action
* param action 
* return sucesso actionid, fail -1

`int ami_send_action(AMI *ami, struct ss_action *action );`

------------


Cria uma nova estrutura e essa estrutura é usado para criar e mandar action. A actionid será criada com o primeiro argumento args[0].
o args será acrescentada mais 1  actionid para argumentos.

    struct s_args s_args_action {
    	char key[MAX_LEN_KEY_ACTION];
    	char value[MAX_LEN_VALUE_ACTION];
    };

    struct ss_action {
    	char name_action[MAX_LEN_NAME_ACTION];
    	int count_args; // a quantidade de argumentos. action->args[0].key - actionid
    	struct s_args *args;
    };
Use destroy_action para liberar esse ponteiro

* param args quantidade de argumentos. O actionid não precisa ser contado e será  preenchido automáticamente
* return poteiro do tipo ss_action. A action será criada automaticamente na primeira posição dos argumentos

`struct ss_action *ami_create_new_action(unsigned int args);`

------------


Libera ponteiro para para estrutura ss_action
* return sucesso 0 sempre

`int ami_destroy_action(struct ss_action *action);`

------------


Libera a lista de eventos passados fora da estrutura, isto é, os eventos através do get_events

* param events lista de eventos obtidas pela função get_events


`void ami_destroy_events(AMI *ami, EVENT *events);`

------------


libera o ponteiro da estrutura response
* param ami instância da estrutura
* param response ponteiro da estrutura response


`void ami_destroy_response(AMI *ami, RESPONSE *response);`

------------


Libera memória da informações da ACTION recebida pela ami
* param ami Instância AMI
* param actionid identifica a action
* return 0 sucesso, -1 actionid não corresponde a nenhuma action

`int ami_destroy_action_return( AMI *ami, const char *actionid );`

------------


Obter os eventos recebido na lista EVENT
* param ami estrutura 
* return events lista de eventos, NULL caso não tenha eventos

`EVENT *ami_get_events(AMI *ami);`

------------


Obter as RESPONSE das actions
* param ami instância que a biblioteca vai identificar
* param actionid da action que vai procurar
* return response ou NULL não há RESPONSE (talvez AMI ainda não retornou)

`RESPONSE *ami_get_actions_response(AMI *ami, const char *actionid);`

------------


obter os eventos das actions 
* param ami instância da biblioteca
* param actionid identificação das actions
* return event ou NULL não há eventos (talvez AMI ainda não enviou)

`EVENT *ami_get_actions_event(AMI *ami, const char *actionid);`

------------


disativa os eventos sem actionid
* param ami
* param status status > 0 eventos OFF, status <= 0 eventos ON 
* return sempre 0

`int ami_set_disable_events( AMI *ami, int status );`

------------


Retorna se os eventos sem actionid estão desativados
* param ami instânca da biblioteca ami, estrutura opaca
* return 0 eventos ON, 1 eventos OFF 

`int ami_get_disable_events(AMI *ami);`

------------


Obtém o valor dos argumentos do Response ou EVENTS
* param ami estrutura opaca
* param args lista de argumentos
\pamra key chave do argumento
* return value ou NULL se o valor é nulo ou não existe

`const char *ami_get_value(AMI *ami, ARGS *args, const char *key );`

------------


Verifica se a chave existi na lista de argumentos
* param ami estrutura opaca
* param args lista de argumentos
* param value a chave 
* return existe 0 ou não existe -1

`int ami_has_key( AMI *ami, ARGS *args, const char *key);`

------------


Busca o primeiro evento encontrado na lista de eventos
* param ami Instância AMI
* param list_event lista de eventos
* param event_name nome do evento que será procurado
* return event ou NULL evento não eocntrado na lista

`EVENT *ami_get_event_name( AMI *ami, EVENT *list_event, const char *event_name );`

------------


Recebe o texto usado quando é conectado ao manager
* param ami estrutura opaca
* return mensagem

`const char *get_welcome( AMI *ami );`

------------


RESPONSE da action de login. ACTION
* param ami estrutura opaca
* return response de login

`RESPONSE *get_response_login(AMI *ami);`


------------

&copy; Copyright Simples IP.