1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
/// What mIRC should do after an exported function returns.
///
/// Strings longer than the host's buffers are truncated at a character boundary; see
/// [`Call::max_response_len`](crate::Call::max_response_len).
///
/// # With `$dllcall()`
///
/// `$dllcall()` evaluates to `$null` at once and the script carries on, so by the time
/// your function returns there is nothing left to halt or return a value to. mIRC then
/// runs a [`Command`](Self::Command), if you returned one, and calls the script's callback
/// alias with the DLL's full path as `$1-`, whatever you returned:
///
/// | Response | `/dll`, `$dll()` | `$dllcall()` |
/// |------------|----------------------------------|-------------------------------------|
/// | `Halt` | halts the calling script | no effect |
/// | `Continue` | carries on; `$dll()` is `$null` | no effect |
/// | `Command` | runs the command | runs the command, then the callback |
/// | `Return` | `$dll()` evaluates to the value | no effect; the value is lost |
///
/// To get a result back from a `$dllcall()`, return a [`Command`](Self::Command) that runs
/// your callback with the result, such as `Response::command_with("fetch_done $1-", value)`,
/// and pass `noop` (from mIRC 6.17; before that, an alias of your own) as the `$dllcall()`
/// callback. (Verified in mIRC 7.83.)
///
/// **Returned commands are delivered reliably, even when `$dllcall()`s overlap.** mIRC
/// keeps each DLL's pending `$dllcall()` result in a single slot, which another call into
/// the same DLL can overwrite before mIRC processes it, losing the command. mirust queues
/// the command itself instead and has mIRC call back into the DLL to run it, so each
/// command runs exactly once, in the order the calls finished. mIRC's own `$dllcall()`
/// callback can still run for the wrong call, or twice, when calls overlap; that's why it
/// should be `noop`. The exception is [`Config::keep_loaded(false)`](crate::Config::keep_loaded),
/// where the DLL doesn't stay loaded long enough to queue anything. See the README for
/// details.
/// Types an exported function can return.
///
/// `String` and `&str` become [`Response::Return`], and `()` becomes [`Response::Continue`].