prosody
ced174f29d9a
doc/net.server.lua

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody

Annotate

doc/net.server.lua @ 9527:ced174f29d9a

stanza_router: Remove deprecation warning for core routing functions from global scope (deprecated in 0.9)
author Kim Alvefur <zash@zash.se>
date Sun, 21 Oct 2018 14:45:22 +0200
parent 9295:6c7d2fb0d369
child 9846:9a0da809ed4a
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8532
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
1 -- Prosody IM
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
2 -- Copyright (C) 2014,2016 Daurnimator
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
3 --
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
4 -- This project is MIT/X11 licensed. Please see the
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
5 -- COPYING file in the source package for more information.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
6
9295
6c7d2fb0d369 doc/net.server.lua: Not an actual source file, instruct luacheck to ignore it
Matthew Wild <mwild1@gmail.com>
parents: 8781
diff changeset
7 --luacheck: ignore
6c7d2fb0d369 doc/net.server.lua: Not an actual source file, instruct luacheck to ignore it
Matthew Wild <mwild1@gmail.com>
parents: 8781
diff changeset
8
8532
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
9 --[[
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
10 This file is a template for writing a net.server compatible backend.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
11 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
12
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
13 --[[
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
14 Read patterns (also called modes) can be one of:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
15 - "*a": Read as much as possible
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
16 - "*l": Read until end of line
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
17 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
18
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
19 --- Handle API
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
20 local handle_mt = {};
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
21 local handle_methods = {};
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
22 handle_mt.__index = handle_methods;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
23
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
24 function handle_methods:set_mode(new_pattern)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
25 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
26
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
27 function handle_methods:setlistener(listeners)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
28 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
29
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
30 function handle_methods:setoption(option, value)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
31 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
32
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
33 function handle_methods:ip()
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
34 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
35
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
36 function handle_methods:starttls(sslctx)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
37 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
38
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
39 function handle_methods:write(data)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
40 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
41
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
42 function handle_methods:close()
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
43 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
44
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
45 function handle_methods:pause()
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
46 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
47
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
48 function handle_methods:resume()
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
49 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
50
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
51 --[[
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
52 Returns
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
53 - socket: the socket object underlying this handle
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
54 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
55 function handle_methods:socket()
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
56 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
57
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
58 --[[
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
59 Returns
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
60 - boolean: if an ssl context has been set on this handle
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
61 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
62 function handle_methods:ssl()
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
63 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
64
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
65
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
66 --- Listeners API
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
67 local listeners = {}
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
68
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
69 --[[ connect
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
70 Called when a client socket has established a connection with it's peer
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
71 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
72 function listeners.onconnect(handle)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
73 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
74
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
75 --[[ incoming
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
76 Called when data is received
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
77 If reading data failed this will be called with `nil, "error message"`
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
78 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
79 function listeners.onincoming(handle, buff, err)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
80 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
81
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
82 --[[ status
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
83 Known statuses:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
84 - "ssl-handshake-complete"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
85 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
86 function listeners.onstatus(handle, status)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
87 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
88
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
89 --[[ disconnect
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
90 Called when the peer has closed the connection
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
91 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
92 function listeners.ondisconnect(handle)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
93 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
94
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
95 --[[ drain
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
96 Called when the handle's write buffer is empty
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
97 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
98 function listeners.ondrain(handle)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
99 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
100
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
101 --[[ readtimeout
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
102 Called when a socket inactivity timeout occurs
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
103 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
104 function listeners.onreadtimeout(handle)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
105 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
106
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
107 --[[ detach: Called when other listeners are going to be removed
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
108 Allows for clean-up
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
109 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
110 function listeners.ondetach(handle)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
111 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
112
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
113 --- Top level functions
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
114
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
115 --[[ Returns the syscall level event mechanism in use.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
116
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
117 Returns:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
118 - backend: e.g. "select", "epoll"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
119 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
120 local function get_backend()
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
121 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
122
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
123 --[[ Starts the event loop.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
124
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
125 Returns:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
126 - "quitting"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
127 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
128 local function loop()
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
129 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
130
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
131 --[[ Stop a running loop()
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
132 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
133 local function setquitting(quit)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
134 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
135
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
136
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
137 --[[ Links to two handles together, so anything written to one is piped to the other
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
138
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
139 Arguments:
8728
41c959c5c84b Fix spelling throughout the codebase [codespell]
Kim Alvefur <zash@zash.se>
parents: 8532
diff changeset
140 - sender, receiver: handles to link
8532
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
141 - buffersize: maximum #bytes until sender will be locked
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
142 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
143 local function link(sender, receiver, buffersize)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
144 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
145
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
146 --[[ Binds and listens on the given address and port
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
147 If `sslctx` is given, the connecting clients will have to negotiate an SSL session
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
148
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
149 Arguments:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
150 - address: address to bind to, may be "*" to bind all addresses. will be resolved if it is a string.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
151 - port: port to bind (as number)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
152 - listeners: a table of listeners
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
153 - pattern: the read pattern
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
154 - sslctx: is a valid luasec constructor
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
155
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
156 Returns:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
157 - handle
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
158 - nil, "an error message": on failure (e.g. out of file descriptors)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
159 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
160 local function addserver(address, port, listeners, pattern, sslctx)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
161 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
162
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
163 --[[ Wraps a lua-socket socket client socket in a handle.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
164 The socket must be already connected to the remote end.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
165 If `sslctx` is given, a SSL session will be negotiated before listeners are called.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
166
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
167 Arguments:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
168 - socket: the lua-socket object to wrap
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
169 - ip: returned by `handle:ip()`
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
170 - port:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
171 - listeners: a table of listeners
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
172 - pattern: the read pattern
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
173 - sslctx: is a valid luasec constructor
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
174 - typ: the socket type, one of:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
175 - "tcp"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
176 - "tcp6"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
177 - "udp"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
178
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
179 Returns:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
180 - handle, socket
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
181 - nil, "an error message": on failure (e.g. )
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
182 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
183 local function wrapclient(socket, ip, serverport, listeners, pattern, sslctx)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
184 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
185
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
186 --[[ Connects to the given address and port
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
187 If `sslctx` is given, a SSL session will be negotiated before listeners are called.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
188
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
189 Arguments:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
190 - address: address to connect to. will be resolved if it is a string.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
191 - port: port to connect to (as number)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
192 - listeners: a table of listeners
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
193 - pattern: the read pattern
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
194 - sslctx: is a valid luasec constructor
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
195 - typ: the socket type, one of:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
196 - "tcp"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
197 - "tcp6"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
198 - "udp"
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
199
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
200 Returns:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
201 - handle
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
202 - nil, "an error message": on failure (e.g. out of file descriptors)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
203 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
204 local function addclient(address, port, listeners, pattern, sslctx, typ)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
205 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
206
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
207 --[[ Close all handles
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
208 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
209 local function closeall()
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
210 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
211
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
212 --[[ The callback should be called after `delay` seconds.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
213 The callback should be called with the time at the point of firing.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
214 If the callback returns a number, it should be called again after that many seconds.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
215
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
216 Arguments:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
217 - delay: number of seconds to wait
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
218 - callback: function to call.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
219 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
220 local function add_task(delay, callback)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
221 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
222
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
223 --[[ Adds a handler for when a signal is fired.
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
224 Optional to implement
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
225 callback does not take any arguments
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
226
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
227 Arguments:
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
228 - signal_id: the signal id (as number) to listen for
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
229 - handler: callback
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
230 ]]
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
231 local function hook_signal(signal_id, handler)
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
232 end
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
233
8781
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
234 --[[ Adds a low-level FD watcher
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
235 Arguments:
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
236 - fd_number: A non-negative integer representing a file descriptor or
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
237 object with a :getfd() method returning one
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
238 - on_readable: Optional callback for when the FD is readable
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
239 - on_writable: Optional callback for when the FD is writable
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
240
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
241 Returns:
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
242 - net.server handle
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
243 ]]
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
244 local function watchfd(fd_number, on_readable, on_writable)
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
245 end
8532
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
246
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
247 return {
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
248 get_backend = get_backend;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
249 loop = loop;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
250 setquitting = setquitting;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
251 link = link;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
252 addserver = addserver;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
253 wrapclient = wrapclient;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
254 addclient = addclient;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
255 closeall = closeall;
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
256 hook_signal = hook_signal;
8781
53178b6ba589 net.server: Add watchfd, a simple API for watching file descriptors
Kim Alvefur <zash@zash.se>
parents: 8728
diff changeset
257 watchfd = watchfd;
8532
17c754b81234 doc: Add template / API specification for net.server (thanks Daurnimator)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
258 }