Biblioteca Firecast.Messaging
A biblioteca Firecast.Messaging contém funções que tratam as notificações que o Firecast dispara para todos os plug-ins através de mensagens.
Em resumo, existem 2 tipos de eventos que o SDK 3 permite o programador "tratar":
- Eventos de tags/controles - São eventos específicos de cada controle.
- Mensagens do Firecast - São acontecimentos que são compartilhado com todos os plugins instalados, pois podem ser de interesse de todos. Exemplos: Quando a conexão do RRPG cai, quando o usuário entra em uma nova mesa, etc..
Esta biblioteca auxilia na manipulação do segundo tipo de evento descrito acima.
Exemplo de uso:
|
-- Primeiro, é necessário usar a unidade "firecast.lua"
require("firecast.lua");
-- Agora é possível acessar as funções da biblioteca
Firecast.Messaging.FUNCAO_DA_BIBLIOTECA(Parametro1, Parametro2, ...);
|
Funções da biblioteca Firecast.Messaging
|
function Firecast.Messaging.newReceiver(messageName, callbackFunction [, filters])
|
Cria e retorna um objeto que representa a "escuta" de mensagens eventos.
Parâmetros:
- messageName - uma cadeia de caracteres definindo qual mensagem-evento a escuta deve ouvir. Para saber quais mensagens você pode escutar, veja Lista de Mensagens Eventos do Firecast.
- callbackFunction - uma função que será invocada sempre que a escuta captar uma mensagem. Quando invocada, a função recebe no primeiro parâmetro uma tabela/objeto lua contendo as propriedades da mensagem. Cada mensagem-evento possui sua própria lista de atributos e você deve, portanto, consultar Lista de Mensagens-Eventos do Firecast para mais detalhes..
- (OPCIONAL) filters - Uma tabela/objeto Lua contendo filtros que a escuta deve verificar para decidir se deve invocar "callbackFunction" ou não. Exemplo:
- Filters= {from="Login"}. A escuta só disparará "callbackFunction" se a mensagem possuir um atributo de nome "from" com conteúdo igual a "Login".
Retorno:
- Um objeto representando a escuta instalada ou nil caso falhe
Observações:
- Mantenha referência ao objeto retornado enquanto a escuta for necessária. Se o objeto for liberado da memória pelo coletor de lixo, a escuta será desinstalada automaticamente.
- A função não falha se você informar, no parâmetro "messageName", uma identificação de mensagem não esteja na lista Lista de Mensagens-Eventos do Firecast, mas, provavelmente, a escuta nunca irá disparará a função "callbackFunction".
- É possível cancelar a escuta de 3 maneiras:
- Invocar a função receiverObj:disable() do objeto retornado, conforme exemplo abaixo
- Retornar explicitamente false na "callbackFunction"
- Deixar o coletor de lixo do Lua coletar o objeto, eventualmente.
- A diferença básica entre Firecast.Messaging.newReceiver e Firecast.Messaging.listen é a forma de gerenciar o ciclo de vida da escuta.
Exemplo:
|
require("firecast.lua");
local receiverObj = Firecast.Messaging.newReceiver("SessionLost",
function (msg)
-- This function will be called when the Firecast connection is lost
showMessage("The connect was lost!");
end);
-- To disable the receiver:
receiverObj:disable(); -- disable right now
receiverObj = nil; -- let the garbage collector disable the receiver
|
|
function Firecast.listen(messageName, callbackFunction [, filters])
ou
function Firecast.Messaging.listen(messageName, callbackFunction [, filters])
|
Instala uma "escuta" de mensagens eventos.
Parâmetros:
- messageName - uma cadeia de caracteres definindo qual mensagem-evento a escuta deve ouvir. Para saber quais mensagens você pode escutar, veja Lista de Mensagens Eventos do Firecast.
- callbackFunction - uma função que será invocada sempre que a escuta captar uma mensagem. Quando invocada, a função recebe no primeiro parâmetro uma tabela/objeto lua contendo as propriedades da mensagem. Cada mensagem-evento possui sua própria lista de atributos e você deve, portanto, consultar Lista de Mensagens-Eventos do Firecast para mais detalhes..
- (OPCIONAL) filters - Uma tabela/objeto Lua contendo filtros que a escuta deve verificar para decidir se deve invocar "callbackFunction" ou não. Exemplo:
- Filters= {from="Login"}. A escuta só disparará "callbackFunction" se a mensagem possuir um atributo de nome "from" com conteúdo igual a "Login".
Retorno:
- Um número identificando a escuta instalada ou nil caso falhe. Você pode utilizar este valor na função Firecast.Messaging.unlisten para cancelar a escuta .
Observações:
Exemplo:
|
require("firecast.lua");
Firecast.Messaging.listen("SessionLost",
function (detalhesDaMensagem)
-- Esta função será chamada quando a conexão do RRPG for perdida
showMessage("A conexão foi perdida!");
end);
|
|
function Firecast.listenOnce(messageName, callbackFunction [, filters])
ou
function Firecast.Messaging.listenOnce(messageName, callbackFunction [, filters])
|
Instala uma "escuta" de mensagens eventos. O funcionamento é idêntico à da função Firecast.Messaging.listen, porém a escuta é automaticamente desinstalada após captar 1 mensagem.
|
function Firecast.unlisten(listenerId)
ou
function Firecast.Messaging.unlisten(listenerId)
|
Desinstala uma "escuta" que foi previamente instalada pela função Firecast.Messaging.listen ou pela função Firecast.Messaging.listenOnce.
Parâmetros:
|
function Firecast.groupOnceListeners(listenerId1 [, listenerId2 [, listenerId3 [, listenerIdN...]]])
ou
function Firecast.Messaging.groupOnceListeners(listenerId1 [, listenerId2 [, listenerId3 [, listenerIdN...]]])
|
Agrupa "escuta" de mensagens-eventos do tipo once (àquela que capta somente 1 mensagem). Quando OnceListeners são agrupados, a característica de se desinstalar automaticamente após receber a primeira mensagem é "expandida" para o grupo. Isto é, quando o Listener1 captar uma mensagem e se desinstalar, o Listener2, Listener3 e ListenerN são automaticamente desinstalados juntos.
Esta função é especialmente útil em situações que possam resultar 2 ou mais mensagens-eventos distintas. Exemplo: O código requisitou a criação de 1 novo personagem em uma mesa... duas coisas podem acontecer: O servidor pode responder à requisição ou a conexão com o rrpg pode cair. Nesta situação, devemos instalar uma escuta "Quando o servidor responder", uma escuta "Quando a conexão cair" e agrupá-las. Note que se o servidor responder, não estaremos mais interessados se a conexão cair e vice-versa.
Parâmetros:
- listenerId1, listenerId2, listenerId3, listenerId4, listenerId5, listenerIdN... As identificações de escuta que queira agrupar. Este valor é retornado pela função Firecast.Messaging.listenOnce.
- Este é um parâmetro "vararg", isto é, você pode passar quantos valores quiser. Exemplo de chamadas válidas: Firecast.Messaging.groupOnceListeners(id1, id2) ou rrpg.messaging.groupOnceListeners(id1, id2, id3, id4, id5, id7, id8).
Created with the Personal Edition of HelpNDoc: Make your documentation accessible on any device with HelpNDoc
