[[!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 '01:23:45:67:89:AB:CD:EF:FE:DC:BA:98:76:54:32:10'.  

**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