--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/api.mdwn Sun Aug 19 15:28:43 2012 +0300
@@ -0,0 +1,564 @@
+
+[[!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
+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.
+**Return values:** boolean
+
+<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="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]).
+
+- - -
\ No newline at end of file