File "src/xpl/classes/xplmessage.lua"

The object class for xPL messages. It has all the regular message properties (some depending on whether it was parsed/received or created). several methods and an iterator are available to manipulate the key-value list.
No global will be created, it just returns the xplmessage class. The main xPL module will create a global xpl.classes.xplmessage to access it.

Copyright © 2011 Thijs Schreijer

Release: Version 0.1, LuaxPL framework.

Tables

key-value pair Internal representation of a key-value pair.
xplmessage fields/properties Members of the xplmessage object

Functions

msg:__tostring () Meta method to format the message as a string value for transmission
msg:add (key, value) Add a key value pair to the message body.
msg:eachkvp () Creates an iterator for the key-value pair list.
msg:getindex (key, occurence) Gets the index of a key.
msg:getkey (index) Gets the key at a given index
msg:getvalue (key, occurence) get a value from the message body by key
msg:initialize () Initializes the xplmessage.
msg:matchfilter (filter) matches the message against an xplfilter
msg:parse (msgstring) Turn a message string into a message object.
msg:send () Transmits the message onto the xPL network
msg:setvalue (key, value) sets value of a key-value pair in the message body.


Tables

key-value pair
Internal representation of a key-value pair. A table with 2 keys, key and value.

Fields

  • key: the key of the key-value pair
  • value: the value of the key-value pair
xplmessage fields/properties
Members of the xplmessage object

Fields

  • type: the xpl message type; "xpl-cmnd", "xpl-trig", "xpl-stat"
  • from: origin of message; "[IP address]:[port]" (when the internal LuaxPL hub is used), "EXTERNAL_HUB" or "CREATED" (when the message was locally created and not received from the network)
  • hop: hop count
  • source: source address of the message
  • sourcevendor: vendor part of source address (only available if parsed)
  • sourcedevice: device part of source address (only available if parsed)
  • sourceinstance: instance part of source address (only available if parsed)
  • target: target address of the message
  • targetvendor: vendor part of source address (only available if parsed, '*' if target address is '*')
  • targetdevice: device part of source address (only available if parsed, '*' if target address is '*')
  • targetinstance: instance part of source address (only available if parsed, '*' if target address is '*')
  • schema: message schema of the message
  • schemaclass: class part of the message schema (only available if parsed)
  • schematype: type part of the message schema (only available if parsed)
  • kvp: list of key value pairs, where each pair is defined as;
    kvp[i] = { key = 'key value',
               value = 'value value'}

    See msg:eachkvp() for an iterator.

Functions

msg:__tostring ()
Meta method to format the message as a string value for transmission

Usage:

-- Create a new message
local msg = xpl.classes.xplmessage:new({})
 
print(msg) -- this will invoke the __tostring() meta method

Return value:

message as string that can be transmitted onto the xPL network
msg:add (key, value)
Add a key value pair to the message body.

Parameters:

  • key: (string) the key (duplicates are allowed)
  • value: the value to store

Return value:

key-value pair inserted (table with 2 keys; key and value)
msg:eachkvp ()
Creates an iterator for the key-value pair list. The iterator will use the order as specified in the message.

Usage:

for key, value, i in msg:eachkvp() do
    print("KVP ", i, " has key = ", key, ", value = ", value)
end

Return value:

iterator function
msg:getindex (key, occurence)
Gets the index of a key.

Parameters:

  • key: the key to be sought in the mesage body
  • occurence: (optional) in case of duplicate keys the occurence can be specified (default 1)

Return value:

index of the key (at mentioned occurence) in the message body or nil if not found
msg:getkey (index)
Gets the key at a given index

Parameters:

  • index: the index for the message body key-value pair whose key to return

Return value:

key (string) if found or nil otherwise
msg:getvalue (key, occurence)
get a value from the message body by key

Parameters:

  • key: either the key or the index of the key-value pair sought
  • occurence: optional, if a key is specified, the occurence to return if there are duplicates (default 1), will be ignored if an index was provided

Return value:

value (string) as set in the key-value pair, or nil if not found
msg:initialize ()
Initializes the xplmessage. Will be called upon instantiation of an object and hence has little use other than when subclassing the xplmessage object into a new class.
msg:matchfilter (filter)
matches the message against an xplfilter

Parameters:

  • filter: xplfilters object (contains list of filters). In case the filter is nil it will return true (default xpl behaviour with absent filters).

Return value:

true or false based upon matching the filter or not.
msg:parse (msgstring)
Turn a message string into a message object. if called as a method, the parsed message is loaded into the existing object. If called as a function on the super class, a new message object will be created.

Parameters:

  • msgstring: the string containing the message to be parsed

Usage:

-- load a parsed message into the object
local msg, remainder = xpl.classes.xplmessage:new({})
msg, remainder = msg:parse(messagestring)
 
-- parse directly to a new message
local msg, remainder = xpl.classes.xplmessage.parse(messagestring)

Return values:

  1. parsed message object
  2. remainder of input string (characters positioned after the parsed message), or nil if there is no remainder
msg:send ()
Transmits the message onto the xPL network

Return value:

true if succesfull, nil + error otherwise
msg:setvalue (key, value)
sets value of a key-value pair in the message body.

Parameters:

  • key: either the key or index of the key-value pair whose value to update. If a key, then the 1st occurrence will be updated.
  • value: the value to set for the specified key/index

Return value:

key-value pair updated (table with 2 keys; key and value), or nil + error if the key or index wasn't found

Valid XHTML 1.0!