aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/coding_style.txt2
-rw-r--r--doc/names.txt2
-rw-r--r--doc/net.server.lua258
-rw-r--r--doc/session.txt4
4 files changed, 262 insertions, 4 deletions
diff --git a/doc/coding_style.txt b/doc/coding_style.txt
index c9113e81..af44da1a 100644
--- a/doc/coding_style.txt
+++ b/doc/coding_style.txt
@@ -7,7 +7,7 @@ Please try to follow, and feel free to fix code you see not following this stand
== Spacing ==
-No space between function names and parenthesis and parenthesis and paramters:
+No space between function names and parenthesis and parenthesis and parameters:
function foo(bar, baz)
diff --git a/doc/names.txt b/doc/names.txt
index 7a6ab1e9..7026c985 100644
--- a/doc/names.txt
+++ b/doc/names.txt
@@ -15,7 +15,7 @@ Thorns thought of:
Eclaire - Idem (French)
Adel - Random
Younha - Read as "yuna"
- Quezacotl - Mayan gods -> google for correct form and pronounciation
+ Quezacotl - Mayan gods -> google for correct form and pronunciation
Carbuncle - FF8 Guardian Force ^^
Protos - Mars satellite
mins - Derived from minstrel
diff --git a/doc/net.server.lua b/doc/net.server.lua
new file mode 100644
index 00000000..7342c549
--- /dev/null
+++ b/doc/net.server.lua
@@ -0,0 +1,258 @@
+-- Prosody IM
+-- Copyright (C) 2014,2016 Daurnimator
+--
+-- This project is MIT/X11 licensed. Please see the
+-- COPYING file in the source package for more information.
+
+--luacheck: ignore
+
+--[[
+This file is a template for writing a net.server compatible backend.
+]]
+
+--[[
+Read patterns (also called modes) can be one of:
+ - "*a": Read as much as possible
+ - "*l": Read until end of line
+]]
+
+--- Handle API
+local handle_mt = {};
+local handle_methods = {};
+handle_mt.__index = handle_methods;
+
+function handle_methods:set_mode(new_pattern)
+end
+
+function handle_methods:setlistener(listeners)
+end
+
+function handle_methods:setoption(option, value)
+end
+
+function handle_methods:ip()
+end
+
+function handle_methods:starttls(sslctx)
+end
+
+function handle_methods:write(data)
+end
+
+function handle_methods:close()
+end
+
+function handle_methods:pause()
+end
+
+function handle_methods:resume()
+end
+
+--[[
+Returns
+ - socket: the socket object underlying this handle
+]]
+function handle_methods:socket()
+end
+
+--[[
+Returns
+ - boolean: if an ssl context has been set on this handle
+]]
+function handle_methods:ssl()
+end
+
+
+--- Listeners API
+local listeners = {}
+
+--[[ connect
+Called when a client socket has established a connection with it's peer
+]]
+function listeners.onconnect(handle)
+end
+
+--[[ incoming
+Called when data is received
+If reading data failed this will be called with `nil, "error message"`
+]]
+function listeners.onincoming(handle, buff, err)
+end
+
+--[[ status
+Known statuses:
+ - "ssl-handshake-complete"
+]]
+function listeners.onstatus(handle, status)
+end
+
+--[[ disconnect
+Called when the peer has closed the connection
+]]
+function listeners.ondisconnect(handle)
+end
+
+--[[ drain
+Called when the handle's write buffer is empty
+]]
+function listeners.ondrain(handle)
+end
+
+--[[ readtimeout
+Called when a socket inactivity timeout occurs
+]]
+function listeners.onreadtimeout(handle)
+end
+
+--[[ detach: Called when other listeners are going to be removed
+Allows for clean-up
+]]
+function listeners.ondetach(handle)
+end
+
+--- Top level functions
+
+--[[ Returns the syscall level event mechanism in use.
+
+Returns:
+ - backend: e.g. "select", "epoll"
+]]
+local function get_backend()
+end
+
+--[[ Starts the event loop.
+
+Returns:
+ - "quitting"
+]]
+local function loop()
+end
+
+--[[ Stop a running loop()
+]]
+local function setquitting(quit)
+end
+
+
+--[[ Links to two handles together, so anything written to one is piped to the other
+
+Arguments:
+ - sender, receiver: handles to link
+ - buffersize: maximum #bytes until sender will be locked
+]]
+local function link(sender, receiver, buffersize)
+end
+
+--[[ Binds and listens on the given address and port
+If `sslctx` is given, the connecting clients will have to negotiate an SSL session
+
+Arguments:
+ - address: address to bind to, may be "*" to bind all addresses. will be resolved if it is a string.
+ - port: port to bind (as number)
+ - listeners: a table of listeners
+ - pattern: the read pattern
+ - sslctx: is a valid luasec constructor
+
+Returns:
+ - handle
+ - nil, "an error message": on failure (e.g. out of file descriptors)
+]]
+local function addserver(address, port, listeners, pattern, sslctx)
+end
+
+--[[ Wraps a lua-socket socket client socket in a handle.
+The socket must be already connected to the remote end.
+If `sslctx` is given, a SSL session will be negotiated before listeners are called.
+
+Arguments:
+ - socket: the lua-socket object to wrap
+ - ip: returned by `handle:ip()`
+ - port:
+ - listeners: a table of listeners
+ - pattern: the read pattern
+ - sslctx: is a valid luasec constructor
+ - typ: the socket type, one of:
+ - "tcp"
+ - "tcp6"
+ - "udp"
+
+Returns:
+ - handle, socket
+ - nil, "an error message": on failure (e.g. )
+]]
+local function wrapclient(socket, ip, serverport, listeners, pattern, sslctx)
+end
+
+--[[ Connects to the given address and port
+If `sslctx` is given, a SSL session will be negotiated before listeners are called.
+
+Arguments:
+ - address: address to connect to. will be resolved if it is a string.
+ - port: port to connect to (as number)
+ - listeners: a table of listeners
+ - pattern: the read pattern
+ - sslctx: is a valid luasec constructor
+ - typ: the socket type, one of:
+ - "tcp"
+ - "tcp6"
+ - "udp"
+
+Returns:
+ - handle
+ - nil, "an error message": on failure (e.g. out of file descriptors)
+]]
+local function addclient(address, port, listeners, pattern, sslctx, typ)
+end
+
+--[[ Close all handles
+]]
+local function closeall()
+end
+
+--[[ The callback should be called after `delay` seconds.
+The callback should be called with the time at the point of firing.
+If the callback returns a number, it should be called again after that many seconds.
+
+Arguments:
+ - delay: number of seconds to wait
+ - callback: function to call.
+]]
+local function add_task(delay, callback)
+end
+
+--[[ Adds a handler for when a signal is fired.
+Optional to implement
+callback does not take any arguments
+
+Arguments:
+ - signal_id: the signal id (as number) to listen for
+ - handler: callback
+]]
+local function hook_signal(signal_id, handler)
+end
+
+--[[ Adds a low-level FD watcher
+Arguments:
+- fd_number: A non-negative integer representing a file descriptor or
+ object with a :getfd() method returning one
+- on_readable: Optional callback for when the FD is readable
+- on_writable: Optional callback for when the FD is writable
+
+Returns:
+- net.server handle
+]]
+local function watchfd(fd_number, on_readable, on_writable)
+end
+
+return {
+ get_backend = get_backend;
+ loop = loop;
+ setquitting = setquitting;
+ link = link;
+ addserver = addserver;
+ wrapclient = wrapclient;
+ addclient = addclient;
+ closeall = closeall;
+ hook_signal = hook_signal;
+ watchfd = watchfd;
+}
diff --git a/doc/session.txt b/doc/session.txt
index fc6eec17..c1f99947 100644
--- a/doc/session.txt
+++ b/doc/session.txt
@@ -15,12 +15,12 @@ session {
full_jid -- convenience for the above 3 as string in username@host/resource form (not defined before resource binding)
priority -- the resource priority, default: 0
presence -- the last non-directed presence with no type attribute. initially nil. reset to nil on unavailable presence.
- interested -- true if the resource requested the roster. Interested resources recieve roster updates. Initially nil.
+ interested -- true if the resource requested the roster. Interested resources receive roster updates. Initially nil.
roster -- the user's roster. Loaded as soon as the resource is bound (session becomes a connected resource).
-- methods --
send(x) -- converts x to a string, and writes it to the connection
- disconnect(x) -- Disconnect the user and clean up the session, best call sessionmanager.destroy_session() instead of this in most cases
+ close(x) -- Disconnect the user and clean up the session, best call sessionmanager.destroy_session() instead of this in most cases
}
if session.full_jid (also session.roster and session.resource) then this is a "connected resource"