[[!meta title="Lua-loudmouth API reference"]]
[[!toc]]
- - -
<a name="Some.common.principles"></a>
## Some common principles
Most methods can be used in two way:
* to get value they are invoked without their last argument. Returned value is either a value or pair of nil and error message.
* to set value they are invoked with last arg (value) specified. Returned value in most cases is an object, on which operation is performed (to allow chain-initialization).
Every object have pointer method to return pointer (lightuserdata) to underlying C loudmouth structure.
Every module have a bless method to convert given pointer (lightuserdata) to corresponding lua object.
Every unique C loudmouth object have only one corresponding lua object. Thus, result of "[lm.message.bless](#lm.message.bless) ( message1:pointer () )" will be exactly message1 object (not its copy).
Where message handler object is expected, message handler function can be specified. However, you can unregister handler only if you have message handler object.
- - -
- - -
<a name="lm.connection"></a>
## lm.connection
Central module, representing connection to the server.
You should create a new connection object, then open it (establish
connection), then authenticate to the server.
<a name="connection.state"></a>
### connection state
Stirng, representing current [connection state](#connection.state).
**Values:** closed, opening, open, authenticating, authenticated
<a name="handler.priority"></a>
### handler priority
String, according to which handler will be placed into one
of three handler groups.
**Values:** last, normal, first
<a name="disconnect.reason"></a>
### disconnect reason
String, indicating the reason of disconnection occured.
**Values:** ok, ping time out, hup, error, resource conflict, invalid xml, unknown, ping_time_out, resource_conflict, invalid_xml
<a name="lm.connection.new"></a>
### lm.connection.new
Creates a new connection (closed).
**Arguments:** string (server name), lightuserdata (C glib main context object, optional)
**Return values:** [lm connection](#lm.connection) object
<a name="lm.connection.bless"></a>
### lm.connection.bless
Blesses given pointer to [lm connection](#lm.connection) object.
Note: it adds a reference to connection.
**Arguments:** lightuserdata (C [lm connection](#lm.connection) object)
**Return values:** [lm connection](#lm.connection) object
<a name="connection.callback.function"></a>
### connection callback function
User function, that will be called on connection establishment operation end,
eg. successful/unsuccessful opening or authentication.
**Arguments:** [lm connection](#lm.connection) object, boolean (success)
<a name="connection:open"></a>
### connection:open
Opens connection to the server and then calls callback function.
**Arguments:** [connection callback function](#connection.callback.function)
**Return values:** [lm connection](#lm.connection) object or nil, string (error message)
<a name="connection:authenticate"></a>
### connection:authenticate
Tries to authenticate against opened connection, then calls callback function.
**Arguments:** string (username), string (password), string (resource), [connection callback function](#connection.callback.function)
**Return values:** [lm connection](#lm.connection) object or nil, string (error message)
<a name="connection:port"></a>
### connection:port
Gets or sets server port to connect.
**Arguments:** integer (optional)
**Return values:** integer (when called with no args) or [lm connection](#lm.connection) object
<a name="connection:server"></a>
### connection:server
Gets or sets server to connect to.
**Arguments:** string (optional, server name)
**Return values:** string (when called with no args) or [lm connection](#lm.connection) object
<a name="connection:jid"></a>
### connection:jid
Gets or sets jid for connection.
**Arguments:** string (optional)
**Return values:** string (when called with no args) or [lm connection](#lm.connection) object
<a name="connection:keep.alive.rate"></a>
### connection:keep_alive_rate
Gets or sets keep alive packets rate for connection.
Note, that on some platforms there is no get function even in
loudmouth versions, that should have it according to documentation.
integer (optional, seconds)
integer (when called with no args) or [lm connection](#lm.connection) object or nil, string (error message, when get function is not available in loudmouth)
<a name="connection:proxy"></a>
### connection:proxy
Gets or sets proxy server for connection.
**Arguments:** [lm proxy](#lm.proxy) object (optional)
**Return values:** [lm proxy](#lm.proxy) object or nil (when called with no args) or [lm connection](#lm.connection) object
<a name="connection:ssl"></a>
### connection:ssl
Gets or sets ssl object for connection.
**Arguments:** [lm ssl](#lm.ssl) object (optional)
**Return values:** [lm ssl](#lm.ssl) object or nil (when called with no args) or [lm connection](#lm.connection) object
<a name="connection:close"></a>
### connection:close
Close connection.
**Return values:** [lm connection](#lm.connection) object or nil, string (error message)
<a name="connection:status"></a>
### connection:status
Returns string, describing [connection state](#connection.state).
**Return values:** [connection state](#connection.state)
<a name="connection:send"></a>
### connection:send
Sends message. If specified, handler function will be called upon receiving of response to this message.
Handler function can be either a message handler object or just a message handler function.
Message can be raw xml string. However, you cannot use it with handler function.
In short:
* connection, errmsg = [connection:send](#connection:send) ( "raw xml" )
* connection, errmsg = [connection:send](#connection:send) ( message )
* connection, errmsg = [connection:send](#connection:send) ( message, function ( connection, message ) end )
* connection, errmsg = [connection:send](#connection:send) ( message, handler )
If connection is nil, errmsg contains error message.
**Arguments:** [lm message](#lm.message) object/string, [message handler callback function](#message.handler.callback.function)/[lm message handler](#lm.message.handler) object (optional)
**Return values:** [lm connection](#lm.connection) object or nil, string (error message)
<a name="connection:handler"></a>
### connection:handler
Registers or unregisters handler function for a given type of messages.
To unregister handler, omit the priority argument.
To unregister reply handler, omit [message type](#message.type) argument too.
Handler function can be specified as plain function or message handler object.
**Arguments:** [message handler callback function](#message.handler.callback.function) or [lm message handler](#lm.message.handler) object, [message type](#message.type) (optional), [handler priority](#handler.priority) (optional)
**Return values:** [lm connection](#lm.connection) object
<a name="disconnect.callback.function"></a>
### disconnect callback function
Function, that will be called when disconnection occurs.
**Arguments:** [lm connection](#lm.connection) object, [disconnect reason](#disconnect.reason)
<a name="connection:ondisconnect"></a>
### connection:ondisconnect
Sets callback, that will be called on connection disconnect.
**Arguments:** [disconnect callback function](#disconnect.callback.function)
**Return values:** [lm connection](#lm.connection) object
<a name="connection:open.wait"></a>
### connection:open_wait
Synchronous open call, that will block until connection will be opened.
**Return values:** [lm connection](#lm.connection) object or nil, string (error message)
<a name="connection:authenticate.wait"></a>
### connection:authenticate_wait
Synchronous authentication call, that will wait until the end of authentication.
**Arguments:** string (username), string (password), string (resource)
**Return values:** [lm connection](#lm.connection) object or nil, string (error message)
<a name="connection:send.wait"></a>
### connection:send_wait
Synchronous call, that will send message and wait for reply to it.
**Arguments:** [lm message](#lm.message) object
**Return values:** [lm message](#lm.message) object or nil, string (error message)
<a name="connection:pointer"></a>
### connection:pointer
Returns pointer to underlying C loudmouth structure.
**Return values:** lightuserdata
- - -
- - -
<a name="lm.message"></a>
## lm.message
Module, representing individual message.
Message have a type and optionally a sub type.
Message have a set common methods with message node,
these are name, next, prev, parent, value, child, children,
find_child, attribute, raw, xml and path. They just save
you typing :node() each time and save memory for
one node object.
<a name="message.type"></a>
### message type
Message type (root tag type).
**Values:** message, presence, iq, stream, stream error, stream features, auth, challenge, response, success, failure, proceed, starttls, unknown, stream:stream, stream:error, stream:features, stream_error, stream_features
<a name="message.sub.type"></a>
### message sub type
Message subtype, not all combinations of type and subtype are possible.
**Values:** not set, available, normal, chat, groupchat, headline, unavailable, probe, subscribe, unsubscribe, subscribed, unsubscribed, get, set, result, error, not_set
<a name="lm.message.new"></a>
### lm.message.new
Creates new message object.
Note: you can specify nil as to argument to send message to server.
**Arguments:** string (to), [message type](#message.type), [message sub type](#message.sub.type) (optional)
**Return values:** [lm message](#lm.message) object
<a name="message.table"></a>
### message table
Table describes xml structure of the message, the only exception is mtype key of root table.
mtype is a string of form "<[message type](#message.type)>-<[message sub type](#message.sub.type)>", eg "iq-set".
Best way to learn how this table is organized, is just to look at next example:
lm.message.create { mtype = 'iq-result', to = 'foo@bar.xyz',
command = { xmlns = 'http://jabber.org/protocol/commands', node = 'http://jabber.org/protocol/rc#set-status', status = 'executing', sessionid = 'set-status:aaa3',
x = { xmlns = 'jabber:x:data', type = 'form',
title = { "Change Status" },
instructions = { "Choose the status and status message" },
field = {{ type = 'hidden', var = 'FORM_TYPE',
value = { "http://jabber.org/protocol/rc" },
},{ type = 'list-single', label = 'Status', var = 'status',
required = { },
value = { "online" },
option = {{ label = 'Chat',
value = { "chat" },
},{ label = 'Online',
value = { "online" },
},{ label = 'Away',
value = { "away" },
},{ label = 'Extended Away',
value = { "xa" },
},{ label = 'Do Not Disturb',
value = { "dnd" },
},{ label = 'Invisible',
value = { "invisible" },
},{ label = 'Offline',
value = { "offline" },
}},
},{ type = 'text-single', label = 'Priority', var = 'status-priority',
value = { "5" },
},{ type = 'text-multi', label = 'Message', var = 'status-message' }},
},
},
}
<a name="lm.message.create"></a>
### lm.message.create
Creates new message object and fills it from [message table](#message.table).
Note, that table fields are not checked for their types, so, on wrong input results may be undefined.
**Arguments:** [message table](#message.table)
**Return values:** [lm message](#lm.message) object
<a name="lm.message.bless"></a>
### lm.message.bless
Blesses given pointer to [lm message](#lm.message) object.
**Arguments:** lightuserdata (C [lm message](#lm.message) object)
**Return values:** [lm message](#lm.message) object
<a name="message:node"></a>
### message:node
Returns root node object of message.
**Return values:** [lm message node](#lm.message.node) object
<a name="message:type"></a>
### message:type
Returns two strings: [message type](#message.type) and [message sub type](#message.sub.type).
**Return values:** [message type](#message.type), [message sub type](#message.sub.type)
<a name="message:pointer"></a>
### message:pointer
Returns pointer to underlying C loudmouth structure.
**Return values:** lightuserdata
- - -
- - -
<a name="lm.message.handler"></a>
## lm.message_handler
Module, representing message handling functions.
<a name="message.handler.callback.function"></a>
### message handler callback function
Callback function, used on incoming messages.
Should return true if message has been fully handled and no more
handlers should be called.
**Arguments:** [lm connection](#lm.connection) object, [lm message](#lm.message) object
**Return values:** boolean
<a name="lm.message.handler.new"></a>
### lm.message_handler.new
Creates new message handler object.
**Arguments:** [message handler callback function](#message.handler.callback.function)
**Return values:** [lm message handler](#lm.message.handler) object
<a name="lm.message.handler.bless"></a>
### lm.message_handler.bless
Blesses given pointer to [lm message handler](#lm.message.handler) object.
**Arguments:** lightuserdata (C [lm message handler](#lm.message.handler) object)
**Return values:** [lm message handler](#lm.message.handler) object
<a name="message.handler:invalidate"></a>
### message_handler:invalidate
Invalidates handler.
**Return values:** [lm message handler](#lm.message.handler) object
<a name="message.handler:valid"></a>
### message_handler:valid
Returns true if message handler is still valid.
**Return values:** boolean
<a name="message.handler:pointer"></a>
### message_handler:pointer
Returns pointer to underlying C loudmouth structure.
**Return values:** lightuserdata
- - -
- - -
<a name="lm.message.node"></a>
## lm.message_node
Object, representing xml node of the message.
Cannot be created directly, only as a part of message tree.
<a name="lm.message.node.bless"></a>
### lm.message_node.bless
Blesses given pointer to [lm message node](#lm.message.node) object.
**Arguments:** lightuserdata (C [lm message node](#lm.message.node) object)
**Return values:** [lm message node](#lm.message.node) object
<a name="message.node:name"></a>
### message_node:name
Gets a name of message node.
**Return values:** string
<a name="message.node:next"></a>
### message_node:next
Gets next message node.
**Return values:** [lm message node](#lm.message.node) object or nil
<a name="message.node:prev"></a>
### message_node:prev
Gets previous message node.
**Return values:** [lm message node](#lm.message.node) object or nil
<a name="message.node:parent"></a>
### message_node:parent
Gets parent message node.
**Return values:** [lm message node](#lm.message.node) object or nil
<a name="message.node:value"></a>
### message_node:value
Gets or sets a value of message node.
**Arguments:** string (optional value)
**Return values:** string (if called without arguments) or [lm message node](#lm.message.node) object
<a name="message.node:child"></a>
### message_node:child
Gets or creates child node object with given name.
If name is omitted, first child node is returned.
**Arguments:** string (name, optional), string (optional value)
**Return values:** [lm message node](#lm.message.node) object or nil
<a name="message.node:children"></a>
### message_node:children
Returns iterator over child nodes of given node. Optionally filters childs by name.
**Arguments:** string (name, optional)
**Return values:** iterator function, [lm message node](#lm.message.node) object, nil
<a name="message.node:find.child"></a>
### message_node:find_child
Searches for node with a given name over all node subtree.
**Arguments:** string (name)
**Return values:** [lm message node](#lm.message.node) object or nil
<a name="message.node:raw"></a>
### message_node:raw
Gets or sets raw mode flag for node.
When set, value of node will not be escaped.
**Arguments:** boolean (optional)
**Values:** boolean (if called with no apguments) or [lm message node](#lm.message.node) object
<a name="message.node:attribute"></a>
### message_node:attribute
Gets or sets value of node attribute with a given name.
**Arguments:** string (name), string (optional value)
**Return values:** string (when called with one aprgument) or [lm message node](#lm.message.node) object
<a name="message.node:xml"></a>
### message_node:xml
Returns node representation in xml.
**Return values:** string
<a name="message.node:path"></a>
### message_node:path
Returns node with specified path to it.
If any element in a path cannot be found, it returns nil.
**Arguments:** string (node name), ...
**Return values:** [lm message node](#lm.message.node) object or nil
<a name="message.node:pointer"></a>
### message_node:pointer
Returns pointer to underlying C structure.
**Return values:** lightuserdata
- - -
- - -
<a name="lm.proxy"></a>
## lm.proxy
Object, containing information about proxy-server for connection.
Create object, set it's parameters, and then attach to connection
with 'proxy' method.
<a name="proxy.type"></a>
### proxy type
Stirng, specifying proxy-server type. The only type supported for now is http.
**Values:** http, none
<a name="lm.proxy.new"></a>
### lm.proxy.new
Creates new proxy object.
Note, you should specify either none of args or both.
**Arguments:** [proxy type](#proxy.type), string (optional proxy server name), integer (optional server port)
**Return values:** [lm proxy](#lm.proxy) object
<a name="lm.proxy.bless"></a>
### lm.proxy.bless
Blesses given pointer to [lm proxy](#lm.proxy) object.
**Arguments:** lightuserdata (C [lm proxy](#lm.proxy) object)
**Return values:** [lm proxy](#lm.proxy) object
<a name="proxy:type"></a>
### proxy:type
Gets or sets proxy server type.
**Arguments:** [proxy type](#proxy.type) (optional)
**Return values:** [proxy type](#proxy.type) (when called with no args) or [lm proxy](#lm.proxy) object
<a name="proxy:server"></a>
### proxy:server
Gets or sets proxy server name.
**Arguments:** string (optional)
**Return values:** string (when called with no args) or [lm proxy](#lm.proxy) object
<a name="proxy:port"></a>
### proxy:port
Gets or sets proxy server port.
**Arguments:** integer (optional)
**Return values:** integer (when called with no args) or [lm proxy](#lm.proxy) object
<a name="proxy:username"></a>
### proxy:username
Gets or sets username to authenticate to proxy server with.
**Arguments:** string (optional)
**Return values:** string (when called with no args) or [lm proxy](#lm.proxy) object
<a name="proxy:password"></a>
### proxy:password
Gets or sets password to authenticate to proxy server with.
**Arguments:** string (optional)
**Return values:** string (when called with no args) or [lm proxy](#lm.proxy) object
<a name="proxy:pointer"></a>
### proxy:pointer
Returns pointer to underlying C structure.
**Return values:** lightuserdata
- - -
- - -
<a name="lm.ssl"></a>
## lm.ssl
Object, containing information about ssl abilities for connection.
Create, set parameters, and attach to connection with 'ssl' method.
<a name="ssl.status"></a>
### ssl status
String, representing what problem have current ssl session.
**Values:** no cert found, untrusted cert, cert expired, cert not activated, cert hostname mismatch, cert fingerprint mismatch, generic error
<a name="ssl.callback.function"></a>
### ssl callback function
User function, called when ssl error happens.
**Arguments:** userdata ([lm ssl](#lm.ssl) object), [argument enum field](#argument.enum.field) ([ssl status](#ssl.status))
**Return values:** boolean (false if connection process should be terminated)
<a name="lm.ssl.new"></a>
### lm.ssl.new
Creates new ssl object for use with connection.
You can specify server key fingerprint, callback function for error handling,
both, or neither. Though, fingerprint should go before callback function.
SSL fingerprint is a string like 'SHA256:ABCDEF123456...' (or
'01:23:45:67:89:AB:CD:EF:FE:DC:BA:98:76:54:32:10' for LM versions, older than 1.5.3).
**Arguments:** string (optional ssl fingerprint), [ssl callback function](#ssl.callback.function) (optional)
**Return values:** userdata ([lm ssl](#lm.ssl) object)
<a name="lm.ssl.bless"></a>
### lm.ssl.bless
Blesses given pointer to [lm ssl](#lm.ssl) object.
**Arguments:** lightuserdata (C [lm ssl](#lm.ssl) object)
**Return values:** userdata ([lm ssl](#lm.ssl) object)
<a name="lm.ssl.supported"></a>
### lm.ssl.supported
Indicates if SSL is supported by loudmouth library and what kind of
ssl fingerprint is used.
**Return values:** nil or string ("MD5" or "SHA256")
<a name="ssl:ca.path"></a>
### ssl:ca_path
Set path to trusted ssl certificates. Argument must be a name of a PEM file
or a name of directory with hashed certificates.
**Arguments:** string (path)
**Return values:** [lm ssl](#lm.ssl) object
<a name="ssl:cipher.list"></a>
### ssl:cipher_list
Set list of allowed ciphers (colon-separated). Names may vary depending on ssl
implementation in use.
**Arguments:** string (cipher list)
**Return values:** [lm ssl](#lm.ssl) object
<a name="ssl:fingerprint"></a>
### ssl:fingerprint
Returns fingerprint of remote server.
**Return values:** string or nil
<a name="ssl:tls"></a>
### ssl:tls
Sets or returns use of starttls by this ssl object.
**Arguments:** boolean (use starttls), boolean (require starttls)
or
**Return values:** boolean (use starttls), boolean (require starttls)
<a name="ssl:pointer"></a>
### ssl:pointer
Returns pointer to underlying C structure.
**Return values:** lightuserdata
- - -
- - -
<a name="Utility.Lua.Routines"></a>
## Utility Lua Routines
To handle conversion of enums and flag fields to/from human-readable strings.
<a name="argument.enum.field"></a>
### argument enum field
String that will be converted to number or just plain number, that will be passed as is.
Note, that if enum name is not recognized no error will be raised and default vale will be used.
<a name="return.enum.field"></a>
### return enum field
String. If no string found, plain number will be returned.
<a name="argument.flags.field"></a>
### argument flags field
Can be just plain number, then it is passed as is.
Can be a string, then it is recognized as a single enabled flag.
Or can be a table of the following format:
* integer keys should have string values, that will be used as enabled flag names or numerical values, that will be just ORed;
* string keys should be flag names, that will be enabled, if corresponding value contains true value.
<a name="returned.flags.field"></a>
### returned flags field
Is always a table with present flag names as keys with true values.
Not present flags are not present in table either.
Not recognized values, if present, will be stored as a number in a first sequential table member (table[1]).
- - -