mirror of
https://github.com/jlu5/PyLink.git
synced 2024-11-30 23:09:23 +01:00
64 lines
3.0 KiB
Markdown
64 lines
3.0 KiB
Markdown
# PyLink hooks reference
|
|
|
|
## Introduction
|
|
|
|
In PyLink, protocol modules communicate with plugins through a system of hooks. This has the benefit of being IRCd-independent, allowing most plugins to function regardless of the IRCd being used.
|
|
Each hook payload is formatted as a Python `list`, with three arguments `(numeric, command, args)`:
|
|
|
|
1) **numeric**: The sender of the message (UID).
|
|
|
|
2) **command**: The command name (hook name) of the payload. These are *always* UPPERCASE, and those starting with "PYLINK_" indicate hooks sent out by IRC objects themselves, that don't require protocol modules to send.
|
|
|
|
3) **args**: The hook data (args), a Python `dict`, with different data keys depending on the command given.
|
|
|
|
Note that the `ts` key is *automatically added* (using the current time) to all hook data dicts that don't include it - such a key should only be provided if the command the uplink IRCd send has a TS value itself.
|
|
|
|
### Example syntax
|
|
|
|
The command `:42XAAAAAB PRIVMSG #endlessvoid :test` would result in the following raw hook data:
|
|
|
|
- `['42XAAAAAB', 'PRIVMSG', {'target': '#endlessvoid', 'text': 'test', 'ts': 1451174041}]`
|
|
|
|
On UnrealIRCd, because SETHOST is mapped to CHGHOST, `:GL SETHOST blah` would return the raw hook data of this (with the nick converted into UID by the UnrealIRCd protocol module):
|
|
|
|
- `['001ZJZW01', 'CHGHOST', {'ts': 1451174512, 'target': '001ZJZW01', 'newhost': 'blah'}]`
|
|
|
|
Some hooks, like MODE, are more complex and can include the entire state of a channel! This will be further described later. `:GL MODE #chat +o PyLink-devel` is converted into (pretty-printed for readability):
|
|
|
|
```
|
|
['001ZJZW01',
|
|
'MODE',
|
|
{'modes': [('+o', '38QAAAAAA')],
|
|
'oldchan': {'modes': set(),
|
|
'prefixmodes': {'admins': set(),
|
|
'halfops': set(),
|
|
'ops': set(),
|
|
'owners': set(),
|
|
'voices': set()},
|
|
'topic': '',
|
|
'topicset': False,
|
|
'ts': 1451169448,
|
|
'users': {'38QAAAAAA', '001ZJZW01'}},
|
|
'target': '#chat',
|
|
'ts': 1451174702}]
|
|
```
|
|
|
|
## Core hooks
|
|
|
|
The following hooks are required for PyLink's basic functioning.
|
|
|
|
- **ENDBURST**: `{}` - Although the hook data is empty, this should be sent whenever a server finishes its burst. The sender should be the server that finishes bursting.
|
|
<br>
|
|
Plugins like Relay need this to know that the uplink has finished bursting all its users!
|
|
|
|
- **PYLINK_DISCONNECT**: `{}` - This is sent to plugins by the IRC objects when their network has disconnected. The sender (numeric) is **None** in this case.
|
|
|
|
- **PYLINK_SPAWNMAIN**: `{'olduser': olduserobj}` - This is sent whenever `Irc.spawnMain()` is called to (re)spawn the main PyLink client, for example to rejoin it from a KILL. It basically tells plugins that the UID of the main PyLink client has changed, while giving them the old data too.
|
|
|
|
## IRC command hooks
|
|
|
|
The following hooks represent regular IRC commands sent between servers.
|
|
|
|
<br><br>
|
|
(under construction)
|