File Intercom.lua

Functions

Intercom:broadcast (msg, lifetime) Broadcast a messsage.
Intercom:createReply (msg) Optional method to initialize a fresh message for replying.
The other possibility is just to reuse the received message for replying.
Intercom:listen (method, object, fromList, ival) Listen to messages from specified plugins, to me.
Intercom:listenForBroadcast (method, object, fromList, ival) Listen to broadcast messages from specified plugins, to anyone.
Intercom:new (t) Constructor for new instance.
Intercom:newClass (t) Constructor for extending class.
Intercom:sendAndReceive (msg, to, tmo, fromName) Send message to specified plugin and wait for reply.
Intercom:sendMessage (msg, to) Send message to destination (unsolicited-inbox), and do not expect nor wait for reply.
Intercom:sendReply (msg, to) Send message that is the reply to an inbound (unsolicited "command" message).
Intercom:stopBroadcastListening (object) Stop broadcast listener tied to specified object.
Intercom:stopListening (object) Stop listener tied to specified object.


Functions

Intercom:broadcast (msg, lifetime)
Broadcast a messsage.

Parameters:

  • msg: (table, required) message to be broadcast.
  • lifetime: (number, optional) lifetime in seconds, else defaults to whatever was initialized when intercom object created (e.g. 10 seconds).

Usage:

  • message will exist for specified time for any broadcast listeners to hear, then it's deleted (by sender - listeners just make note to not reprocess).
  • broadcast messages do not warrant replies, but receiver is free to send message to broadcaster when broadcast message is received... 
Intercom:createReply (msg)
Optional method to initialize a fresh message for replying.
The other possibility is just to reuse the received message for replying.

Parameters:

  • msg:
Intercom:listen (method, object, fromList, ival)
Listen to messages from specified plugins, to me.

Parameters:

  • method: (function, required) callback function - must be method.
  • object: (Class instance object, optional) object containing callback method. - must not be closed object, or must contain __seen member table.
  • fromList: (table as set, default = accept from anyone including self) keys are plugin ids from who unsolicited messages will be accepted, values must evaluate to boolean true.
  • ival: (number, optional) polling interval, else accept default.

Usage:

  • returns immediately after starting task, which runs until shutdown.
  • object may be nil, and method may be function, as long as plugin will never try to stop listening. 
Intercom:listenForBroadcast (method, object, fromList, ival)
Listen to broadcast messages from specified plugins, to anyone.

Parameters:

  • method: (function, required) callback function - must be method.
  • object: (Class instance object, optional) object containing callback method. - must not be closed object, or must contain __seen member table.
  • fromList: (table as set, default = accept from anyone including self) keys are plugin ids from who unsolicited messages will be accepted, values must evaluate to boolean true.
  • ival: (number, optional) polling interval, else accept default.

Usage:

    returns immediately after starting task, which runs until shutdown. 
Intercom:new (t)
Constructor for new instance.

Parameters:

  • t: (table) initial object members, all optional, including:
    dir (string, default=catalog dir) path to root of messaging dirs.
    pollingInterval (number, default=.1) seconds between polling for incoming messages and/or replies.
    - faster means more responsive but more disk wear. Default is .1 second - seems a nice balanced value.
    - you can go down to .01 second (windows base clock frequency), for ultra-fast messaging,
    - or up to a half second if speed is not a concern, to save disk wear.
    broadcastLifetime (number, default=10) seconds for broadcast messages to last before they're assumed to have been heard, and are cleaned up.
    addlNames (array of strings, default={}) names of additional plugin entities to be communicating via the intercom, e.g. "Background" (corresponding from-address {pluginId}.Background).
Intercom:newClass (t)
Constructor for extending class.

Parameters:

  • t:
Intercom:sendAndReceive (msg, to, tmo, fromName)
Send message to specified plugin and wait for reply.

Parameters:

  • msg:
  • to:
  • tmo:
  • fromName:

Usage:

    must be called from a task. 

Return values:

  1. reply (table) or nil if no reply
  2. errm (string) error message if no reply.
Intercom:sendMessage (msg, to)
Send message to destination (unsolicited-inbox), and do not expect nor wait for reply.

Parameters:

  • msg: (table, required) 'name' is only required member, but 'content' may be nice...
  • to: (string, required) destination plugin id.

Usage:

    Not for internal use - use private methods instead. 

Return values:

  1. status (boolean) true => sent.
  2. message (string) error message if not sent.
Intercom:sendReply (msg, to)
Send message that is the reply to an inbound (unsolicited "command" message).

Parameters:

  • msg: (table, required) 'name' is only required member, but 'content' may be nice...
  • to: (string, required) destination plugin id - often msg.from

Usage:

  • Maybe best to recompute message content, then resend original message (since it already has some members assigned as needed) - but its your call...
  • presently throws error if problems sending, but that may change - note: need not be called from task, although typically is. 
Intercom:stopBroadcastListening (object)
Stop broadcast listener tied to specified object.

Parameters:

  • object: Must be same object as passed to listen-for-broadcast function.
Intercom:stopListening (object)
Stop listener tied to specified object.

Parameters:

  • object: Must be same object as passed to listen function.

Valid XHTML 1.0!