Mercurial > prosody-hg

comparison doc/net.server.lua @ 8532:17c754b81234

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