author | Matthew Wild <mwild1@gmail.com> |
Tue, 16 Apr 2024 12:58:08 +0100 | |
changeset 5889 | 54b451c3790c |
parent 5846 | ed82916e5796 |
permissions | -rw-r--r-- |
5798
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
1 |
--- |
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
2 |
labels: |
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
3 |
- 'Stage-Alpha' |
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
4 |
summary: Manually configure extended service discovery info |
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
5 |
... |
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
6 |
|
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
7 |
XEP-0128 defines a way for servers to provide custom information via service |
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
8 |
discovery. Various XEPs and plugins make use of this functionality, so that |
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
9 |
e.g. clients can look up necessary information. |
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
10 |
|
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
11 |
This module allows the admin to manually configure service discovery |
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
12 |
extensions in the config file. It may be useful as a way to advertise certain |
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
13 |
information. |
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
14 |
|
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
15 |
Everything configured here is publicly visible to other XMPP entities. |
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
16 |
|
5846
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
17 |
**Note:** This module was rewritten in February 2024, the configuration is not |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
18 |
compatible with the previous version of the module. |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
19 |
|
5798
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
20 |
## Configuration |
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
21 |
|
5846
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
22 |
The `server_info_extensions` option accepts a list of custom fields to include |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
23 |
in the server info form. |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
24 |
|
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
25 |
A field has three required properties: |
5798
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
26 |
|
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
27 |
- `type` - usually `text-single` or `list-multi` |
5846
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
28 |
- `var` - the field name (see below) |
5798
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
29 |
- `value` the field value |
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
30 |
|
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
31 |
Example configuration: |
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
32 |
|
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
33 |
``` lua |
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
34 |
server_info = { |
5846
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
35 |
-- Advertise that our maximum speed is 88 mph |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
36 |
{ type = "text-single", var = "speed", value = "88" }; |
5798
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
37 |
|
5846
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
38 |
-- Advertise that the time is 1:20 AM and zero seconds |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
39 |
{ type = "text-single", var = "time", value = "01:21:00" }; |
5798
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
40 |
} |
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
41 |
``` |
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
42 |
|
5846
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
43 |
The `var` attribute is used to uniquely identify fields. Every `var` should be |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
44 |
registered with the XSF [form registry](https://xmpp.org/registrar/formtypes.html#http:--jabber.org-network-serverinfo), |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
45 |
or prefixed with a custom namespace using Clark notation, e.g. `{https://example.com}my-field-name`. This is to prevent |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
46 |
collisions. |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
47 |
|
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
48 |
## Developers |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
49 |
|
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
50 |
Developers of other modules can add fields to the form at runtime: |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
51 |
|
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
52 |
```lua |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
53 |
module:depends("server_info"); |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
54 |
|
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
55 |
module:add_item("server-info-fields", { |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
56 |
{ type = "text-single", var = "speed", value = "88" }; |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
57 |
{ type = "text-single", var = "time", value = "01:21:00" }; |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
58 |
}); |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
59 |
``` |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
60 |
|
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
61 |
Prosody will ensure they are removed if your module is unloaded. |
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
62 |
|
5798
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
63 |
## Compatibility |
174c77da03f5
mod_server_info: New module to add custom service extension forms to disco
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
64 |
|
5846
ed82916e5796
mod_server_info: Rewrite/backport from Prosody 1ce18cb3e6cc
Matthew Wild <mwild1@gmail.com>
parents:
5798
diff
changeset
|
65 |
This module should be compatible with Prosody 0.12 and later. |