5 - A API para canais TCP

• Canais
  • alua.channel.create
    • Servidor
    • Cliente
• Servidor TCP
  • server:close
  • server.closed
  • server:gethandler
  • server:sethandler
  • server.type
• Cliente TCP
  • client:close
  • client.closed
  • client:gethandler
  • client:receive
  • client:send
  • client:sethandler
  • client:settimeout
  • client.type

alua.channel.create(type, config [, handlers])

O que faz

Cria novos canais do tipo especificado.

Descrição

Esta função serve de interface para a criação de vários tipos diferentes de canais. A criação de cada tipo de canal tem o seu retorno específico. Como os canais podem ter características diferentes, as funções exportadas podem ter algumas variações.

type é uma string contendo a descrição do tipo de canal a ser criado. Se o tipo de canal necessita de parâmetros auxiliares, estes fornecidos através de config. Os tratadores de eventos são passados na tabela handlers.

Consulte a documentação do tipo de canal desejado para detalhes sobre a criação e uso dos mesmos.

Voltar ao topo

alua.channel.create("tcp:server", config [, handlers])

O que faz

Cria um canal servidor TCP.

Descrição

Cria um servidor TCP que pode receber conexões de clientes. O parâmetro type deve conter a string "tcp:server" e o parametro config deve ser uma tabela com chave e valor descritos a seguir:

Um canal servidor TCP dispara os eventos de (i) nova conexão de cliente e (ii) fechamento de conexão. Tratadores podem ser instalados para receber esses eventos. A tabela a seguir mostra o nome do evento, descrição e a assinatura da função que pode ser definida para tratar o evento.

Em geral, o evento accept é utilizado para configurar os tratadores para o novo cliente e close para liberação de recursos.

A tabela handlers pode ser informada no ato da criação do canal para instalar os tratadores para o servidor. handlers possui como chave o nome do evento e como valor a função de tratamento. Este parâmetro é opcional, e a instalação e modificação dos tratadores pode ser feita usando funções específicas sobre o canal. E não é obrigatória a instalação de tratadores para todos os eventos.

O parâmetro newclient recebido pelo tratador do evento accept é um canal cliente TCP que representa a nova conexão recebida. O parâmetro server recebido pelos tratadores de accept e close é o próprio canal servidor TCP.

Valor de retorno

Retorna um identificador para o canal servidor TCP.

Exemplo de uso

   require("alua")

   local clients = 0

   ------
   --- Tratadores do cliente
   --
   local function clt_read(conn)
     local str, err = conn:receive("*l")
     if str then
       print(str)
     elseif err == "closed" then
       conn:close()
     end
   end

   local function clt_close(conn)
     clients = clients - 1
     print(clients .. " cliente(s) conectado(s)")
   end

   ------
   --- Tratadores do servidor
   --
   local function srv_accept(clt, srv)
     clients = clients + 1
     print(clients .. " cliente(s) conectado(s)")

     -- Set the handler for the new client connection
     clt:sethandler("read", clt_read)
     clt:sethandler("close", clt_close)
   end


   local srv_handlers = {
     accept = srv_accept,
   }

   -- Cria o canal servidor
   local config = {addr = "127.0.0.1", port = 6080}
   local srv, err = alua.channel.create("tcp:server", config, srv_handlers)
   assert(srv, err)
   print("Servidor iniciado...")

   alua.loop()

Voltar ao topo

alua.channel.create("tcp:client", config [, handlers])

O que faz

Cria um canal client TCP.

Descrição

Cria um client TCP que se conecta com um servidor TCP. O parâmetro type deve conter a string "tcp:client" e o parametro config deve ser uma tabela com chave e valor descritos a seguir:

Um canal cliente TCP dispara os eventos de (i) pronto para a escrita, indicando que chamadas da função de envio de dados não bloqueará o processo, (ii) pronto para a leitura, indicando há dados para serem lidos da rede e (iii) fechamento de conexão. Tratadores podem ser instalados para receber esses eventos. A tabela a seguir mostra o nome do evento, descrição e a assinatura da função que pode ser definida para tratar o evento.

A tabela handlers pode ser informada no ato da criação do canal para instalar os tratadores para o servidor. handlers possui como chave o nome do evento e como valor a função de tratamento. Este parâmetro é opcional, e a instalação e modificação dos tratadores pode ser feita usando funções específicas sobre o canal. E não é obrigatória a instalação de tratadores para todos os eventos.

O parâmetro client recebido pelos tratadores é o próprio canal cliente TCP.

Valor de retorno

Retorna um identificador para o canal cliente TCP.

Exemplo de uso

   require("alua")

   -- Cria o canal cliente
   local config = {addr = "127.0.0.1", port = 6080}
   local clt, err = alua.channel.create("tcp:client", config)
   assert(clt, err)

   -- Cria um temporizador para enviar as mensagens
   function send()
     clt:send("uma linha de texto\n")
   end

   local t, err = alua.timer.create(3, send)
   assert(t, err)

   alua.loop()

Voltar ao topo

server:close()

O que faz

Fecha o canal servidor TCP.

Descrição

Esta função fecha a conexão TCP do servidor, impedindo que novas conexões clientes sejam recebidas. Ela também modifica o valor do atributo server.type para true, indicando que o canal está fechado.

Voltar ao topo

server.closed

O que faz

Indica se o canal está fechado.

Descrição

Após o fechamento do canal através da função server:close, este campo possui valor true. Caso contrário, seu valor é nil.

Voltar ao topo

server:gethandler(name)

O que faz

Retorna o tratador de evento do canal servidor TCP.

Descrição

Esta função permite recuperar o tratador dos eventos lançados pelo servidor. O argumento name é o nome do evento desejado.

Valor de retorno

Retorna a função tratadora do evento, se houver. Caso contrário, retorna nil.

Voltar ao topo

server:sethandler(name, func)

O que faz

Modifica o tratador de um evento do canal servidor TCP.

Descrição

A função func será considerada o novo tratador para o evento name. Se func for nil, então o evento antigo é removido e o evento permanece sem tratador.

Voltar ao topo

server:sethandler(name, func)

O que faz

Modifica o tratador de um evento do canal servidor TCP.

Descrição

A função func será considerada o novo tratador para o evento name. Se func for nil, então o evento antigo é removido e o evento permanece sem tratador.

Voltar ao topo

server.type

O que faz

Informação sobre o tipo de canal.

Descrição

Contém a string "tcp:server" indicando o tipo do canal.

Voltar ao topo

client:close()

O que faz

Fecha o canal cliente TCP.

Descrição

Esta função fecha a conexão e modifica o campo client.closed para true.

Voltar ao topo

client.closed

O que faz

Indica se o canal está fechado.

Descrição

Após o fechamento do canal através da função client:close, este campo possui o valor true. Caso contrário, seu valor é nil.

Voltar ao topo

client:gethandler(name)

O que faz

Retorna o tratador de evento do canal cliente TCP.

Descrição

Esta função permite recuperar o tratador dos eventos lançados pelo cliente. O argumento name é o nome do evento desejado.

Valor de retorno

Retorna a função tratadora do evento, se houver. Caso contrário, retorna nil.

Voltar ao topo

client:receive([pattern])

O que faz

Recebe informações do canal cliente TCP.

Descrição

Esta função recebe dados do canal e pode opcionalmente o argumento pattern que é um padrão para o recebimento desses dados. Os padrões suportados são:

• '*a': lê dados até o fechamento da conexão;
• '*l': lê uma linha de texto do canal. As linhas são delimitadas pelo caractere LF (ASCII 10), opcionalmente precedido pelo caractere CR (ASCII 13). Esses caracteres não são incluídos na linha.
• número: lê o especificado número de bytes do canal.

Caso nenhum padrão seja informado, é assumido o padão '*l' para leitura de linha.

Valor de retorno

Em caso de sucesso, retorna os dados de acordo com o padrão escolhido. Se um erro ocorrer, a função retorna o valor nil, seguido de uma mensagem de erro.

Voltar ao topo

client:send(data)

O que faz

Envia informações pelo canal cliente TCP.

Descrição

data deve ser uma string contendo os dados a serem enviados.

Valor de retorno

Em caso de sucesso, retorna o número de bytes enviados pelo canal. Se um erro ocorrer, a função retorna o valor nil, seguido de uma mensagem de erro.

Voltar ao topo

client:sethandler(name, func)

O que faz

Modifica o tratador de um evento do canal cliente TCP.

Descrição

A função func será considerada o novo tratador para o evento name. Se func for nil, então o evento antigo é removido e o evento permanece sem tratador.

Voltar ao topo

client:settimeout(value [, mode])

O que faz

Altera o tempo máximo de espera para que o envio e o recebimento de dados seja terminado.

Descrição

Por padrão, as funções client:send e client:receive do canal são bloqueantes. client:settimeout modifica o limite de tempo que essas funções esperam até a operação ser completada.

O parâmetro value indica o tempo máximo de espera (em segundos - use números decimais para milisegundos, por exemplo). Sendo que esse tempo pode ser aplicado nos modos (definidos pelo argumento mode):

Para cancelar o tempo de máximo de espera, passe o valor nil ou um número negativo como argumento value, tornando as operações bloqueantes novamente.

Voltar ao topo

client.type

O que faz

Informação sobre o tipo de canal.

Descrição

Contém a string "tcp:client" indicando o tipo do canal.

Voltar ao topo

Última atualização: 20-Mai-2008 16:31