48
|
1 |
|
|
2 |
[[!meta title="Lua-loudmouth API reference"]] |
|
3 |
|
|
4 |
[[!toc]] |
|
5 |
|
|
6 |
|
|
7 |
- - - |
|
8 |
|
|
9 |
<a name="Some.common.principles"></a> |
|
10 |
## Some common principles |
|
11 |
Most methods can be used in two way: |
|
12 |
|
|
13 |
* to get value they are invoked without their last argument. Returned value is either a value or pair of nil and error message. |
|
14 |
* 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). |
|
15 |
|
|
16 |
Every object have pointer method to return pointer (lightuserdata) to underlying C loudmouth structure. |
|
17 |
Every module have a bless method to convert given pointer (lightuserdata) to corresponding lua object. |
|
18 |
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). |
|
19 |
Where message handler object is expected, message handler function can be specified. However, you can unregister handler only if you have message handler object. |
|
20 |
|
|
21 |
- - - |
|
22 |
|
|
23 |
- - - |
|
24 |
|
|
25 |
<a name="lm.connection"></a> |
|
26 |
## lm.connection |
|
27 |
Central module, representing connection to the server. |
|
28 |
You should create a new connection object, then open it (establish |
|
29 |
connection), then authenticate to the server. |
|
30 |
|
|
31 |
<a name="connection.state"></a> |
|
32 |
### connection state |
|
33 |
Stirng, representing current [connection state](#connection.state). |
|
34 |
**Values:** closed, opening, open, authenticating, authenticated |
|
35 |
|
|
36 |
<a name="handler.priority"></a> |
|
37 |
### handler priority |
|
38 |
String, according to which handler will be placed into one |
|
39 |
of three handler groups. |
|
40 |
**Values:** last, normal, first |
|
41 |
|
|
42 |
<a name="disconnect.reason"></a> |
|
43 |
### disconnect reason |
|
44 |
String, indicating the reason of disconnection occured. |
|
45 |
**Values:** ok, ping time out, hup, error, resource conflict, invalid xml, unknown, ping_time_out, resource_conflict, invalid_xml |
|
46 |
|
|
47 |
<a name="lm.connection.new"></a> |
|
48 |
### lm.connection.new |
|
49 |
Creates a new connection (closed). |
|
50 |
**Arguments:** string (server name), lightuserdata (C glib main context object, optional) |
|
51 |
**Return values:** [lm connection](#lm.connection) object |
|
52 |
|
|
53 |
<a name="lm.connection.bless"></a> |
|
54 |
### lm.connection.bless |
|
55 |
Blesses given pointer to [lm connection](#lm.connection) object. |
|
56 |
Note: it adds a reference to connection. |
|
57 |
**Arguments:** lightuserdata (C [lm connection](#lm.connection) object) |
|
58 |
**Return values:** [lm connection](#lm.connection) object |
|
59 |
|
|
60 |
<a name="connection.callback.function"></a> |
|
61 |
### connection callback function |
|
62 |
User function, that will be called on connection establishment operation end, |
|
63 |
eg. successful/unsuccessful opening or authentication. |
|
64 |
**Arguments:** [lm connection](#lm.connection) object, boolean (success) |
|
65 |
|
|
66 |
<a name="connection:open"></a> |
|
67 |
### connection:open |
|
68 |
Opens connection to the server and then calls callback function. |
|
69 |
**Arguments:** [connection callback function](#connection.callback.function) |
|
70 |
**Return values:** [lm connection](#lm.connection) object or nil, string (error message) |
|
71 |
|
|
72 |
<a name="connection:authenticate"></a> |
|
73 |
### connection:authenticate |
|
74 |
Tries to authenticate against opened connection, then calls callback function. |
|
75 |
**Arguments:** string (username), string (password), string (resource), [connection callback function](#connection.callback.function) |
|
76 |
**Return values:** [lm connection](#lm.connection) object or nil, string (error message) |
|
77 |
|
|
78 |
<a name="connection:port"></a> |
|
79 |
### connection:port |
|
80 |
Gets or sets server port to connect. |
|
81 |
**Arguments:** integer (optional) |
|
82 |
**Return values:** integer (when called with no args) or [lm connection](#lm.connection) object |
|
83 |
|
|
84 |
<a name="connection:server"></a> |
|
85 |
### connection:server |
|
86 |
Gets or sets server to connect to. |
|
87 |
**Arguments:** string (optional, server name) |
|
88 |
**Return values:** string (when called with no args) or [lm connection](#lm.connection) object |
|
89 |
|
|
90 |
<a name="connection:jid"></a> |
|
91 |
### connection:jid |
|
92 |
Gets or sets jid for connection. |
|
93 |
**Arguments:** string (optional) |
|
94 |
**Return values:** string (when called with no args) or [lm connection](#lm.connection) object |
|
95 |
|
|
96 |
<a name="connection:keep.alive.rate"></a> |
|
97 |
### connection:keep_alive_rate |
|
98 |
Gets or sets keep alive packets rate for connection. |
|
99 |
Note, that on some platforms there is no get function even in |
|
100 |
loudmouth versions, that should have it according to documentation. |
|
101 |
integer (optional, seconds) |
|
102 |
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) |
|
103 |
|
|
104 |
<a name="connection:proxy"></a> |
|
105 |
### connection:proxy |
|
106 |
Gets or sets proxy server for connection. |
|
107 |
**Arguments:** [lm proxy](#lm.proxy) object (optional) |
|
108 |
**Return values:** [lm proxy](#lm.proxy) object or nil (when called with no args) or [lm connection](#lm.connection) object |
|
109 |
|
|
110 |
<a name="connection:ssl"></a> |
|
111 |
### connection:ssl |
|
112 |
Gets or sets ssl object for connection. |
|
113 |
**Arguments:** [lm ssl](#lm.ssl) object (optional) |
|
114 |
**Return values:** [lm ssl](#lm.ssl) object or nil (when called with no args) or [lm connection](#lm.connection) object |
|
115 |
|
|
116 |
<a name="connection:close"></a> |
|
117 |
### connection:close |
|
118 |
Close connection. |
|
119 |
**Return values:** [lm connection](#lm.connection) object or nil, string (error message) |
|
120 |
|
|
121 |
<a name="connection:status"></a> |
|
122 |
### connection:status |
|
123 |
Returns string, describing [connection state](#connection.state). |
|
124 |
**Return values:** [connection state](#connection.state) |
|
125 |
|
|
126 |
<a name="connection:send"></a> |
|
127 |
### connection:send |
|
128 |
Sends message. If specified, handler function will be called upon receiving of response to this message. |
|
129 |
Handler function can be either a message handler object or just a message handler function. |
|
130 |
Message can be raw xml string. However, you cannot use it with handler function. |
|
131 |
In short: |
|
132 |
|
|
133 |
* connection, errmsg = [connection:send](#connection:send) ( "raw xml" ) |
|
134 |
* connection, errmsg = [connection:send](#connection:send) ( message ) |
|
135 |
* connection, errmsg = [connection:send](#connection:send) ( message, function ( connection, message ) end ) |
|
136 |
* connection, errmsg = [connection:send](#connection:send) ( message, handler ) |
|
137 |
|
|
138 |
If connection is nil, errmsg contains error message. |
|
139 |
**Arguments:** [lm message](#lm.message) object/string, [message handler callback function](#message.handler.callback.function)/[lm message handler](#lm.message.handler) object (optional) |
|
140 |
**Return values:** [lm connection](#lm.connection) object or nil, string (error message) |
|
141 |
|
|
142 |
<a name="connection:handler"></a> |
|
143 |
### connection:handler |
|
144 |
Registers or unregisters handler function for a given type of messages. |
|
145 |
To unregister handler, omit the priority argument. |
|
146 |
To unregister reply handler, omit [message type](#message.type) argument too. |
|
147 |
Handler function can be specified as plain function or message handler object. |
|
148 |
**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) |
|
149 |
**Return values:** [lm connection](#lm.connection) object |
|
150 |
|
|
151 |
<a name="disconnect.callback.function"></a> |
|
152 |
### disconnect callback function |
|
153 |
Function, that will be called when disconnection occurs. |
|
154 |
**Arguments:** [lm connection](#lm.connection) object, [disconnect reason](#disconnect.reason) |
|
155 |
|
|
156 |
<a name="connection:ondisconnect"></a> |
|
157 |
### connection:ondisconnect |
|
158 |
Sets callback, that will be called on connection disconnect. |
|
159 |
**Arguments:** [disconnect callback function](#disconnect.callback.function) |
|
160 |
**Return values:** [lm connection](#lm.connection) object |
|
161 |
|
|
162 |
<a name="connection:open.wait"></a> |
|
163 |
### connection:open_wait |
|
164 |
Synchronous open call, that will block until connection will be opened. |
|
165 |
**Return values:** [lm connection](#lm.connection) object or nil, string (error message) |
|
166 |
|
|
167 |
<a name="connection:authenticate.wait"></a> |
|
168 |
### connection:authenticate_wait |
|
169 |
Synchronous authentication call, that will wait until the end of authentication. |
|
170 |
**Arguments:** string (username), string (password), string (resource) |
|
171 |
**Return values:** [lm connection](#lm.connection) object or nil, string (error message) |
|
172 |
|
|
173 |
<a name="connection:send.wait"></a> |
|
174 |
### connection:send_wait |
|
175 |
Synchronous call, that will send message and wait for reply to it. |
|
176 |
**Arguments:** [lm message](#lm.message) object |
|
177 |
**Return values:** [lm message](#lm.message) object or nil, string (error message) |
|
178 |
|
|
179 |
<a name="connection:pointer"></a> |
|
180 |
### connection:pointer |
|
181 |
Returns pointer to underlying C loudmouth structure. |
|
182 |
**Return values:** lightuserdata |
|
183 |
|
|
184 |
- - - |
|
185 |
|
|
186 |
- - - |
|
187 |
|
|
188 |
<a name="lm.message"></a> |
|
189 |
## lm.message |
|
190 |
Module, representing individual message. |
|
191 |
Message have a type and optionally a sub type. |
|
192 |
Message have a set common methods with message node, |
|
193 |
these are name, next, prev, parent, value, child, children, |
|
194 |
find_child, attribute, raw, xml and path. They just save |
|
195 |
you typing :node() each time and save memory for |
|
196 |
one node object. |
|
197 |
|
|
198 |
<a name="message.type"></a> |
|
199 |
### message type |
|
200 |
Message type (root tag type). |
|
201 |
**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 |
|
202 |
|
|
203 |
<a name="message.sub.type"></a> |
|
204 |
### message sub type |
|
205 |
Message subtype, not all combinations of type and subtype are possible. |
|
206 |
**Values:** not set, available, normal, chat, groupchat, headline, unavailable, probe, subscribe, unsubscribe, subscribed, unsubscribed, get, set, result, error, not_set |
|
207 |
|
|
208 |
<a name="lm.message.new"></a> |
|
209 |
### lm.message.new |
|
210 |
Creates new message object. |
|
211 |
Note: you can specify nil as to argument to send message to server. |
|
212 |
**Arguments:** string (to), [message type](#message.type), [message sub type](#message.sub.type) (optional) |
|
213 |
**Return values:** [lm message](#lm.message) object |
|
214 |
|
|
215 |
<a name="message.table"></a> |
|
216 |
### message table |
|
217 |
Table describes xml structure of the message, the only exception is mtype key of root table. |
|
218 |
mtype is a string of form "<[message type](#message.type)>-<[message sub type](#message.sub.type)>", eg "iq-set". |
|
219 |
Best way to learn how this table is organized, is just to look at next example: |
|
220 |
|
|
221 |
lm.message.create { mtype = 'iq-result', to = 'foo@bar.xyz', |
|
222 |
command = { xmlns = 'http://jabber.org/protocol/commands', node = 'http://jabber.org/protocol/rc#set-status', status = 'executing', sessionid = 'set-status:aaa3', |
|
223 |
x = { xmlns = 'jabber:x:data', type = 'form', |
|
224 |
title = { "Change Status" }, |
|
225 |
instructions = { "Choose the status and status message" }, |
|
226 |
field = {{ type = 'hidden', var = 'FORM_TYPE', |
|
227 |
value = { "http://jabber.org/protocol/rc" }, |
|
228 |
},{ type = 'list-single', label = 'Status', var = 'status', |
|
229 |
required = { }, |
|
230 |
value = { "online" }, |
|
231 |
option = {{ label = 'Chat', |
|
232 |
value = { "chat" }, |
|
233 |
},{ label = 'Online', |
|
234 |
value = { "online" }, |
|
235 |
},{ label = 'Away', |
|
236 |
value = { "away" }, |
|
237 |
},{ label = 'Extended Away', |
|
238 |
value = { "xa" }, |
|
239 |
},{ label = 'Do Not Disturb', |
|
240 |
value = { "dnd" }, |
|
241 |
},{ label = 'Invisible', |
|
242 |
value = { "invisible" }, |
|
243 |
},{ label = 'Offline', |
|
244 |
value = { "offline" }, |
|
245 |
}}, |
|
246 |
},{ type = 'text-single', label = 'Priority', var = 'status-priority', |
|
247 |
value = { "5" }, |
|
248 |
},{ type = 'text-multi', label = 'Message', var = 'status-message' }}, |
|
249 |
}, |
|
250 |
}, |
|
251 |
} |
|
252 |
|
|
253 |
|
|
254 |
|
|
255 |
<a name="lm.message.create"></a> |
|
256 |
### lm.message.create |
|
257 |
Creates new message object and fills it from [message table](#message.table). |
|
258 |
Note, that table fields are not checked for their types, so, on wrong input results may be undefined. |
|
259 |
**Arguments:** [message table](#message.table) |
|
260 |
**Return values:** [lm message](#lm.message) object |
|
261 |
|
|
262 |
<a name="lm.message.bless"></a> |
|
263 |
### lm.message.bless |
|
264 |
Blesses given pointer to [lm message](#lm.message) object. |
|
265 |
**Arguments:** lightuserdata (C [lm message](#lm.message) object) |
|
266 |
**Return values:** [lm message](#lm.message) object |
|
267 |
|
|
268 |
<a name="message:node"></a> |
|
269 |
### message:node |
|
270 |
Returns root node object of message. |
|
271 |
**Return values:** [lm message node](#lm.message.node) object |
|
272 |
|
|
273 |
<a name="message:type"></a> |
|
274 |
### message:type |
|
275 |
Returns two strings: [message type](#message.type) and [message sub type](#message.sub.type). |
|
276 |
**Return values:** [message type](#message.type), [message sub type](#message.sub.type) |
|
277 |
|
|
278 |
<a name="message:pointer"></a> |
|
279 |
### message:pointer |
|
280 |
Returns pointer to underlying C loudmouth structure. |
|
281 |
**Return values:** lightuserdata |
|
282 |
|
|
283 |
- - - |
|
284 |
|
|
285 |
- - - |
|
286 |
|
|
287 |
<a name="lm.message.handler"></a> |
|
288 |
## lm.message_handler |
|
289 |
Module, representing message handling functions. |
|
290 |
|
|
291 |
<a name="message.handler.callback.function"></a> |
|
292 |
### message handler callback function |
|
293 |
Callback function, used on incoming messages. |
|
294 |
Should return true if message has been fully handled and no more |
|
295 |
handlers should be called. |
|
296 |
**Arguments:** [lm connection](#lm.connection) object, [lm message](#lm.message) object |
|
297 |
**Return values:** boolean |
|
298 |
|
|
299 |
<a name="lm.message.handler.new"></a> |
|
300 |
### lm.message_handler.new |
|
301 |
Creates new message handler object. |
|
302 |
**Arguments:** [message handler callback function](#message.handler.callback.function) |
|
303 |
**Return values:** [lm message handler](#lm.message.handler) object |
|
304 |
|
|
305 |
<a name="lm.message.handler.bless"></a> |
|
306 |
### lm.message_handler.bless |
|
307 |
Blesses given pointer to [lm message handler](#lm.message.handler) object. |
|
308 |
**Arguments:** lightuserdata (C [lm message handler](#lm.message.handler) object) |
|
309 |
**Return values:** [lm message handler](#lm.message.handler) object |
|
310 |
|
|
311 |
<a name="message.handler:invalidate"></a> |
|
312 |
### message_handler:invalidate |
|
313 |
Invalidates handler. |
|
314 |
**Return values:** [lm message handler](#lm.message.handler) object |
|
315 |
|
|
316 |
<a name="message.handler:valid"></a> |
|
317 |
### message_handler:valid |
|
318 |
Returns true if message handler is still valid. |
|
319 |
**Return values:** boolean |
|
320 |
|
|
321 |
<a name="message.handler:pointer"></a> |
|
322 |
### message_handler:pointer |
|
323 |
Returns pointer to underlying C loudmouth structure. |
|
324 |
**Return values:** lightuserdata |
|
325 |
|
|
326 |
- - - |
|
327 |
|
|
328 |
- - - |
|
329 |
|
|
330 |
<a name="lm.message.node"></a> |
|
331 |
## lm.message_node |
|
332 |
Object, representing xml node of the message. |
|
333 |
Cannot be created directly, only as a part of message tree. |
|
334 |
|
|
335 |
<a name="lm.message.node.bless"></a> |
|
336 |
### lm.message_node.bless |
|
337 |
Blesses given pointer to [lm message node](#lm.message.node) object. |
|
338 |
**Arguments:** lightuserdata (C [lm message node](#lm.message.node) object) |
|
339 |
**Return values:** [lm message node](#lm.message.node) object |
|
340 |
|
|
341 |
<a name="message.node:name"></a> |
|
342 |
### message_node:name |
|
343 |
Gets a name of message node. |
|
344 |
**Return values:** string |
|
345 |
|
|
346 |
<a name="message.node:next"></a> |
|
347 |
### message_node:next |
|
348 |
Gets next message node. |
|
349 |
**Return values:** [lm message node](#lm.message.node) object or nil |
|
350 |
|
|
351 |
<a name="message.node:prev"></a> |
|
352 |
### message_node:prev |
|
353 |
Gets previous message node. |
|
354 |
**Return values:** [lm message node](#lm.message.node) object or nil |
|
355 |
|
|
356 |
<a name="message.node:parent"></a> |
|
357 |
### message_node:parent |
|
358 |
Gets parent message node. |
|
359 |
**Return values:** [lm message node](#lm.message.node) object or nil |
|
360 |
|
|
361 |
<a name="message.node:value"></a> |
|
362 |
### message_node:value |
|
363 |
Gets or sets a value of message node. |
|
364 |
**Arguments:** string (optional value) |
|
365 |
**Return values:** string (if called without arguments) or [lm message node](#lm.message.node) object |
|
366 |
|
|
367 |
<a name="message.node:child"></a> |
|
368 |
### message_node:child |
|
369 |
Gets or creates child node object with given name. |
|
370 |
If name is omitted, first child node is returned. |
|
371 |
**Arguments:** string (name, optional), string (optional value) |
|
372 |
**Return values:** [lm message node](#lm.message.node) object or nil |
|
373 |
|
|
374 |
<a name="message.node:children"></a> |
|
375 |
### message_node:children |
|
376 |
Returns iterator over child nodes of given node. Optionally filters childs by name. |
|
377 |
**Arguments:** string (name, optional) |
|
378 |
**Return values:** iterator function, [lm message node](#lm.message.node) object, nil |
|
379 |
|
|
380 |
<a name="message.node:find.child"></a> |
|
381 |
### message_node:find_child |
|
382 |
Searches for node with a given name over all node subtree. |
|
383 |
**Arguments:** string (name) |
|
384 |
**Return values:** [lm message node](#lm.message.node) object or nil |
|
385 |
|
|
386 |
<a name="message.node:raw"></a> |
|
387 |
### message_node:raw |
|
388 |
Gets or sets raw mode flag for node. |
|
389 |
When set, value of node will not be escaped. |
|
390 |
**Arguments:** boolean (optional) |
|
391 |
**Values:** boolean (if called with no apguments) or [lm message node](#lm.message.node) object |
|
392 |
|
|
393 |
<a name="message.node:attribute"></a> |
|
394 |
### message_node:attribute |
|
395 |
Gets or sets value of node attribute with a given name. |
|
396 |
**Arguments:** string (name), string (optional value) |
|
397 |
**Return values:** string (when called with one aprgument) or [lm message node](#lm.message.node) object |
|
398 |
|
|
399 |
<a name="message.node:xml"></a> |
|
400 |
### message_node:xml |
|
401 |
Returns node representation in xml. |
|
402 |
**Return values:** string |
|
403 |
|
|
404 |
<a name="message.node:path"></a> |
|
405 |
### message_node:path |
|
406 |
Returns node with specified path to it. |
|
407 |
If any element in a path cannot be found, it returns nil. |
|
408 |
**Arguments:** string (node name), ... |
|
409 |
**Return values:** [lm message node](#lm.message.node) object or nil |
|
410 |
|
|
411 |
<a name="message.node:pointer"></a> |
|
412 |
### message_node:pointer |
|
413 |
Returns pointer to underlying C structure. |
|
414 |
**Return values:** lightuserdata |
|
415 |
|
|
416 |
- - - |
|
417 |
|
|
418 |
- - - |
|
419 |
|
|
420 |
<a name="lm.proxy"></a> |
|
421 |
## lm.proxy |
|
422 |
Object, containing information about proxy-server for connection. |
|
423 |
Create object, set it's parameters, and then attach to connection |
|
424 |
with 'proxy' method. |
|
425 |
|
|
426 |
<a name="proxy.type"></a> |
|
427 |
### proxy type |
|
428 |
Stirng, specifying proxy-server type. The only type supported for now is http. |
|
429 |
**Values:** http, none |
|
430 |
|
|
431 |
<a name="lm.proxy.new"></a> |
|
432 |
### lm.proxy.new |
|
433 |
Creates new proxy object. |
|
434 |
Note, you should specify either none of args or both. |
|
435 |
**Arguments:** [proxy type](#proxy.type), string (optional proxy server name), integer (optional server port) |
|
436 |
**Return values:** [lm proxy](#lm.proxy) object |
|
437 |
|
|
438 |
<a name="lm.proxy.bless"></a> |
|
439 |
### lm.proxy.bless |
|
440 |
Blesses given pointer to [lm proxy](#lm.proxy) object. |
|
441 |
**Arguments:** lightuserdata (C [lm proxy](#lm.proxy) object) |
|
442 |
**Return values:** [lm proxy](#lm.proxy) object |
|
443 |
|
|
444 |
<a name="proxy:type"></a> |
|
445 |
### proxy:type |
|
446 |
Gets or sets proxy server type. |
|
447 |
**Arguments:** [proxy type](#proxy.type) (optional) |
|
448 |
**Return values:** [proxy type](#proxy.type) (when called with no args) or [lm proxy](#lm.proxy) object |
|
449 |
|
|
450 |
<a name="proxy:server"></a> |
|
451 |
### proxy:server |
|
452 |
Gets or sets proxy server name. |
|
453 |
**Arguments:** string (optional) |
|
454 |
**Return values:** string (when called with no args) or [lm proxy](#lm.proxy) object |
|
455 |
|
|
456 |
<a name="proxy:port"></a> |
|
457 |
### proxy:port |
|
458 |
Gets or sets proxy server port. |
|
459 |
**Arguments:** integer (optional) |
|
460 |
**Return values:** integer (when called with no args) or [lm proxy](#lm.proxy) object |
|
461 |
|
|
462 |
<a name="proxy:username"></a> |
|
463 |
### proxy:username |
|
464 |
Gets or sets username to authenticate to proxy server with. |
|
465 |
**Arguments:** string (optional) |
|
466 |
**Return values:** string (when called with no args) or [lm proxy](#lm.proxy) object |
|
467 |
|
|
468 |
<a name="proxy:password"></a> |
|
469 |
### proxy:password |
|
470 |
Gets or sets password to authenticate to proxy server with. |
|
471 |
**Arguments:** string (optional) |
|
472 |
**Return values:** string (when called with no args) or [lm proxy](#lm.proxy) object |
|
473 |
|
|
474 |
<a name="proxy:pointer"></a> |
|
475 |
### proxy:pointer |
|
476 |
Returns pointer to underlying C structure. |
|
477 |
**Return values:** lightuserdata |
|
478 |
|
|
479 |
- - - |
|
480 |
|
|
481 |
- - - |
|
482 |
|
|
483 |
<a name="lm.ssl"></a> |
|
484 |
## lm.ssl |
|
485 |
Object, containing information about ssl abilities for connection. |
|
486 |
Create, set parameters, and attach to connection with 'ssl' method. |
|
487 |
|
|
488 |
<a name="ssl.status"></a> |
|
489 |
### ssl status |
|
490 |
String, representing what problem have current ssl session. |
|
491 |
**Values:** no cert found, untrusted cert, cert expired, cert not activated, cert hostname mismatch, cert fingerprint mismatch, generic error |
|
492 |
|
|
493 |
<a name="ssl.callback.function"></a> |
|
494 |
### ssl callback function |
|
495 |
User function, called when ssl error happens. |
|
496 |
**Arguments:** userdata ([lm ssl](#lm.ssl) object), [argument enum field](#argument.enum.field) ([ssl status](#ssl.status)) |
|
497 |
**Return values:** boolean (false if connection process should be terminated) |
|
498 |
|
|
499 |
<a name="lm.ssl.new"></a> |
|
500 |
### lm.ssl.new |
|
501 |
Creates new ssl object for use with connection. |
|
502 |
You can specify server key fingerprint, callback function for error handling, |
|
503 |
both, or neither. Though, fingerprint should go before callback function. |
|
504 |
SSL fingerprint is a string like '01:23:45:67:89:AB:CD:EF:FE:DC:BA:98:76:54:32:10'. |
|
505 |
**Arguments:** string (optional ssl fingerprint), [ssl callback function](#ssl.callback.function) (optional) |
|
506 |
**Return values:** userdata ([lm ssl](#lm.ssl) object) |
|
507 |
|
|
508 |
<a name="lm.ssl.bless"></a> |
|
509 |
### lm.ssl.bless |
|
510 |
Blesses given pointer to [lm ssl](#lm.ssl) object. |
|
511 |
**Arguments:** lightuserdata (C [lm ssl](#lm.ssl) object) |
|
512 |
**Return values:** userdata ([lm ssl](#lm.ssl) object) |
|
513 |
|
|
514 |
<a name="lm.ssl.supported"></a> |
|
515 |
### lm.ssl.supported |
|
516 |
Indicates if SSL is supported by loudmouth library. |
|
517 |
**Return values:** boolean |
|
518 |
|
|
519 |
<a name="ssl:fingerprint"></a> |
|
520 |
### ssl:fingerprint |
|
521 |
Returns fingerprint of remote server. |
|
522 |
**Return values:** string or nil |
|
523 |
|
|
524 |
<a name="ssl:tls"></a> |
|
525 |
### ssl:tls |
|
526 |
Sets or returns use of starttls by this ssl object. |
|
527 |
**Arguments:** boolean (use starttls), boolean (require starttls) |
|
528 |
or |
|
529 |
**Return values:** boolean (use starttls), boolean (require starttls) |
|
530 |
|
|
531 |
<a name="ssl:pointer"></a> |
|
532 |
### ssl:pointer |
|
533 |
Returns pointer to underlying C structure. |
|
534 |
**Return values:** lightuserdata |
|
535 |
|
|
536 |
- - - |
|
537 |
|
|
538 |
- - - |
|
539 |
|
50
|
540 |
<a name="Utility.Lua.Routines"></a> |
|
541 |
## Utility Lua Routines |
|
542 |
To handle conversion of enums and flag fields to/from human-readable strings. |
|
543 |
|
48
|
544 |
<a name="argument.enum.field"></a> |
50
|
545 |
### argument enum field |
48
|
546 |
String that will be converted to number or just plain number, that will be passed as is. |
|
547 |
Note, that if enum name is not recognized no error will be raised and default vale will be used. |
|
548 |
|
|
549 |
<a name="return.enum.field"></a> |
|
550 |
### return enum field |
|
551 |
String. If no string found, plain number will be returned. |
|
552 |
|
|
553 |
<a name="argument.flags.field"></a> |
|
554 |
### argument flags field |
|
555 |
Can be just plain number, then it is passed as is. |
|
556 |
Can be a string, then it is recognized as a single enabled flag. |
|
557 |
Or can be a table of the following format: |
|
558 |
|
|
559 |
* integer keys should have string values, that will be used as enabled flag names or numerical values, that will be just ORed; |
|
560 |
* string keys should be flag names, that will be enabled, if corresponding value contains true value. |
|
561 |
|
|
562 |
<a name="returned.flags.field"></a> |
|
563 |
### returned flags field |
|
564 |
Is always a table with present flag names as keys with true values. |
|
565 |
Not present flags are not present in table either. |
|
566 |
Not recognized values, if present, will be stored as a number in a first sequential table member (table[1]). |
|
567 |
|
|
568 |
- - - |