# HG changeset patch # User Myhailo Danylenko # Date 1345379323 -10800 # Node ID ef69edc792be8a133fca11f0e0caac50ab690f95 # Parent 4bf7ef2fea2eff1cb5b78cbdf5f851b521fdcea1 Rearrange docs diff -r 4bf7ef2fea2e -r ef69edc792be CMakeLists.txt --- a/CMakeLists.txt Fri Aug 19 01:42:20 2011 +0300 +++ b/CMakeLists.txt Sun Aug 19 15:28:43 2012 +0300 @@ -65,6 +65,8 @@ if(DOCGEN_EXECUTABLE) add_custom_command(OUTPUT ${lua-lm_BINARY_DIR}/loudmouth.html COMMAND ${DOCGEN_EXECUTABLE} -f html -t "Lua-loudmouth API reference" -o ${lua-lm_BINARY_DIR}/loudmouth.html -- ${loudmouth_SOURCES} DEPENDS ${DOCGEN_EXECUTABLE} ${loudmouth_SOURCES} WORKING_DIRECTORY ${lua-lm_SOURCE_DIR}) add_custom_target(doc ALL DEPENDS ${lua-lm_BINARY_DIR}/loudmouth.html) + add_custom_command(OUTPUT ${lua-lm_SOURCE_DIR}/docs/api.mdwn COMMAND ${DOCGEN_EXECUTABLE} -f mdwn -t "Lua-loudmouth API reference" -o ${lua-lm_SOURCE_DIR}/docs/api.mdwn -- ${loudmouth_SOURCES} DEPENDS ${DOCGEN_EXECUTABLE} ${loudmouth_SOURCES} WORKING_DIRECTORY ${lua-lm_SOURCE_DIR}) + add_custom_target(update_api DEPENDS ${lua-lm_SOURCE_DIR}/docs/api.mdwn) endif() if(LUA_EXECUTABLE) add_custom_target(test COMMAND env "LUA_PATH=${lua-lm_SOURCE_DIR}/?.lua;${LUA_PATH}" "LUA_CPATH=${lua-lm_SOURCE_DIR}/?.so;${lua-lm_BINARY_DIR}/?.so;${LUA_CPATH}" "${LUA_EXECUTABLE}" "${lua-lm_SOURCE_DIR}/test.lua" "${TEST_USER}" "${TEST_PASSWORD}" "${TEST_TO}" "${TEST_FINGERPRINT}" DEPENDS loudmouth VERBATIM) @@ -104,6 +106,6 @@ if(DOCGEN_EXECUTABLE) install(FILES ${lua-lm_BINARY_DIR}/loudmouth.html DESTINATION share/doc/${CPACK_PACKAGE_NAME}) endif() -install(FILES README TODO COPYING DESTINATION share/doc/${CPACK_PACKAGE_NAME}) +install(FILES docs/readme.mdwn docs/todo.mdwn COPYING DESTINATION share/doc/${CPACK_PACKAGE_NAME}) ## The End ## vim: se ts=4 sw=4: ## diff -r 4bf7ef2fea2e -r ef69edc792be README --- a/README Fri Aug 19 01:42:20 2011 +0300 +++ b/README Sun Aug 19 15:28:43 2012 +0300 @@ -1,53 +1,1 @@ - -This is a lua 5.1 interface for loudmouth jabber client library. - -INSTALLATION - -To install it, you need: -- lua (optional, to run test) -- liblua headers and library -- glib headers and library -- loudmouth headers and library -- cmake -- pkg-config (to detect glib and loudmouth) -- perl (optional, to generate documentation) - -Then do -$ mkdir build -$ cd build -$ cmake .. -$ cmake edit_cache -$ make -# make install - -Debian users can instead of make install do, -$ fakeroot make package -# dpkg -i liblua5.1-*.deb - -Users of other systems can set other CPack generator using cache editor. - -NOTES - -Unfortunately, test script depends on my unfinished (and, probably, never finished) -glib module, and thus is unusable as is. - -This module should be used as follows: -lm = require 'lm' -i.e., you should assign require return value to some variable. - -Loudmouth uses glib main loop to work, thus you should use this module in -a glib loop environment, provided either by your glib-based program or by some -other module, eg lua binding for gtk+. - -LICENSE - -This code underlies terms of GNU GPL v2 or later. You can find it in file COPYING -from this distribution or on a GNU web-site . - -CONTACTS - -I will be happy to get feedback, patches, suggestions, etc. -You can send me email or contact via jabber . - - -- Myhailo Danylenko - +docs/readme.mdwn \ No newline at end of file diff -r 4bf7ef2fea2e -r ef69edc792be TODO --- a/TODO Fri Aug 19 01:42:20 2011 +0300 +++ b/TODO Sun Aug 19 15:28:43 2012 +0300 @@ -1,11 +1,1 @@ - -Verify refcounts of lm objects. Need a decent test script for that. -Some additional lua functions? -Do something about strcasecmp non-portability. -Add versions to dependencies. -Finish parse function? -Do something about debug and logging. - -Get child value method -Xml console interception means? - +docs/todo.mdwn \ No newline at end of file diff -r 4bf7ef2fea2e -r ef69edc792be docs/api.mdwn --- /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]] + + +- - - + + +## 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. + +- - - + +- - - + + +## 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. + + +### connection state +Stirng, representing current [connection state](#connection.state). +**Values:** closed, opening, open, authenticating, authenticated + + +### handler priority +String, according to which handler will be placed into one +of three handler groups. +**Values:** last, normal, first + + +### 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 + + +### 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 + + +### 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 + + +### 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) + + +### 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) + + +### 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) + + +### 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 + + +### 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 + + +### 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 + + +### 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) + + +### 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 + + +### 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 + + +### connection:close +Close connection. +**Return values:** [lm connection](#lm.connection) object or nil, string (error message) + + +### connection:status +Returns string, describing [connection state](#connection.state). +**Return values:** [connection state](#connection.state) + + +### 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) + + +### 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 + + +### disconnect callback function +Function, that will be called when disconnection occurs. +**Arguments:** [lm connection](#lm.connection) object, [disconnect reason](#disconnect.reason) + + +### 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 + + +### 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) + + +### 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) + + +### 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) + + +### connection:pointer +Returns pointer to underlying C loudmouth structure. +**Return values:** lightuserdata + +- - - + +- - - + + +## 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. + + +### 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 + + +### 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 + + +### 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 + + +### 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' }}, + }, + }, + } + + + + +### 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 + + +### 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 + + +### message:node +Returns root node object of message. +**Return values:** [lm message node](#lm.message.node) object + + +### 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) + + +### message:pointer +Returns pointer to underlying C loudmouth structure. +**Return values:** lightuserdata + +- - - + +- - - + + +## lm.message_handler +Module, representing message handling functions. + + +### 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 + + +### 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 + + +### 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 + + +### message_handler:invalidate +Invalidates handler. +**Return values:** [lm message handler](#lm.message.handler) object + + +### message_handler:valid +Returns true if message handler is still valid. +**Return values:** boolean + + +### message_handler:pointer +Returns pointer to underlying C loudmouth structure. +**Return values:** lightuserdata + +- - - + +- - - + + +## lm.message_node +Object, representing xml node of the message. +Cannot be created directly, only as a part of message tree. + + +### 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 + + +### message_node:name +Gets a name of message node. +**Return values:** string + + +### message_node:next +Gets next message node. +**Return values:** [lm message node](#lm.message.node) object or nil + + +### message_node:prev +Gets previous message node. +**Return values:** [lm message node](#lm.message.node) object or nil + + +### message_node:parent +Gets parent message node. +**Return values:** [lm message node](#lm.message.node) object or nil + + +### 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 + + +### 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 + + +### 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 + + +### 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 + + +### 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 + + +### 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 + + +### message_node:xml +Returns node representation in xml. +**Return values:** string + + +### 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 + + +### message_node:pointer +Returns pointer to underlying C structure. +**Return values:** lightuserdata + +- - - + +- - - + + +## lm.proxy +Object, containing information about proxy-server for connection. +Create object, set it's parameters, and then attach to connection +with 'proxy' method. + + +### proxy type +Stirng, specifying proxy-server type. The only type supported for now is http. +**Values:** http, none + + +### 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 + + +### 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 + + +### 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 + + +### 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 + + +### 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 + + +### 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 + + +### 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 + + +### proxy:pointer +Returns pointer to underlying C structure. +**Return values:** lightuserdata + +- - - + +- - - + + +## lm.ssl +Object, containing information about ssl abilities for connection. +Create, set parameters, and attach to connection with 'ssl' method. + + +### 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 + + +### 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) + + +### 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) + + +### 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) + + +### lm.ssl.supported +Indicates if SSL is supported by loudmouth library. +**Return values:** boolean + + +### ssl:fingerprint +Returns fingerprint of remote server. +**Return values:** string or nil + + +### 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) + + +### ssl:pointer +Returns pointer to underlying C structure. +**Return values:** lightuserdata + +- - - + +- - - + + +## 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. + + +### return enum field +String. If no string found, plain number will be returned. + + +### 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. + + +### 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 diff -r 4bf7ef2fea2e -r ef69edc792be docs/index.mdwn --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/index.mdwn Sun Aug 19 15:28:43 2012 +0300 @@ -0,0 +1,9 @@ + +[[!meta title="lua-lm"]] + +# Loudmouth interface for lua + +Complete interface for loudmouth XMPP client library. + +[ [[!hg @PN@ desc="SOURCE"]] ] [ [[README|readme]] ] [ [[TODO|todo]] ] [ [[API|api]] ] [ [LOUDMOUTH](http://github.com/mcabber/loudmouth) ] + diff -r 4bf7ef2fea2e -r ef69edc792be docs/readme.mdwn --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/readme.mdwn Sun Aug 19 15:28:43 2012 +0300 @@ -0,0 +1,53 @@ + +This is a lua 5.1 interface for loudmouth jabber client library. + +INSTALLATION + +To install it, you need: +- lua (optional, to run test) +- liblua headers and library +- glib headers and library +- loudmouth headers and library +- cmake +- pkg-config (to detect glib and loudmouth) +- perl (optional, to generate documentation) + +Then do +$ mkdir build +$ cd build +$ cmake .. +$ cmake edit_cache +$ make +# make install + +Debian users can instead of make install do, +$ fakeroot make package +# dpkg -i liblua5.1-*.deb + +Users of other systems can set other CPack generator using cache editor. + +NOTES + +Unfortunately, test script depends on my unfinished (and, probably, never finished) +glib module, and thus is unusable as is. + +This module should be used as follows: +lm = require 'lm' +i.e., you should assign require return value to some variable. + +Loudmouth uses glib main loop to work, thus you should use this module in +a glib loop environment, provided either by your glib-based program or by some +other module, eg lua binding for gtk+. + +LICENSE + +This code underlies terms of GNU GPL v2 or later. You can find it in file COPYING +from this distribution or on a GNU web-site . + +CONTACTS + +I will be happy to get feedback, patches, suggestions, etc. +You can send me email or contact via jabber . + + -- Myhailo Danylenko + diff -r 4bf7ef2fea2e -r ef69edc792be docs/todo.mdwn --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/todo.mdwn Sun Aug 19 15:28:43 2012 +0300 @@ -0,0 +1,11 @@ + +Verify refcounts of lm objects. Need a decent test script for that. +Some additional lua functions? +Do something about strcasecmp non-portability. +Add versions to dependencies. +Finish parse function? +Do something about debug and logging. + +Get child value method +Xml console interception means? +