LuaDoc

• Index

Modules

• xpl
• xpldevice
• xplfilters
• xplhub
• xpllistener
• xpllogger
• xplmessage
• xplnetpresence
• xplsender

Files

• src/xpl/classes/base.lua
• src/xpl/classes/xpldevice.lua
• src/xpl/classes/xplfilter.lua
• src/xpl/classes/xplmessage.lua
• src/xpl/init.lua
• src/xpl/new_device_template.lua
• src/xpl/xplhub.lua
• src/xpl/xpllistener.lua
• src/xpllogger.lua
• src/xplnetpres_conf.lua
• src/xplnetpresence.lua
• src/xplrun.lua
• src/xplrun_config.lua
• src/xplsender.lua

Module "xplmessage"

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

Functions

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