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
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
//! Write mIRC and AdiIRC DLLs in safe, idiomatic Rust.
//!
//! mirust handles the C side of mIRC's DLL interface: the `LoadDll`/`UnloadDll` entry
//! points, the `LOADINFO` handshake, string encoding and buffer sizes across every mIRC
//! release since 5.6. You write ordinary Rust functions that take a [`Call`] and return a
//! [`Response`] (or anything that implements [`IntoResponse`]), and list them in
//! [`export!`]. The entry points are provided for you; use [`config!`] only to change the
//! defaults.
//!
//! ```
//! use mirust::{Call, Response};
//!
//! /// $dll(hello.dll, greet, World) returns "Hello, World!"
//! fn greet(call: Call) -> String {
//! format!("Hello, {}!", call.data())
//! }
//!
//! /// /dll hello.dll shout hi -> echoes "HI" in the active window
//! fn shout(call: Call) -> Response {
//! Response::command_with("echo -a $1-", call.data().to_uppercase())
//! }
//!
//! mirust::export!(greet, shout);
//! # fn main() {}
//! ```
//!
//! Build with `crate-type = ["cdylib"]`, for the architecture of the client that loads the
//! DLL: mIRC is 32-bit x86 only (`i686-pc-windows-msvc`); AdiIRC is x86, x64 or ARM64
//! (`x86_64-pc-windows-msvc`, `aarch64-pc-windows-msvc`), matching the AdiIRC build
//! installed.
//!
//! # What mirust takes care of
//!
//! - **Buffer sizes.** mIRC's `data`/`parms` buffers have grown from 900 bytes to over
//! 10 KB, and `mBytes` was only added in 7.64 (and misreported until 7.84). mirust picks
//! the right size for the running version ([`Host::capacity`]) and truncates responses at
//! a character boundary instead of overflowing.
//! - **Encoding.** Your code always sees `&str`/`String`. mirust requests UTF-16 on mIRC 7+
//! and converts from UTF-8 or the ANSI code page where it has to ([`Encoding`]).
//! - **Version quirks.** mIRC 5.8 – 6.2 misreported their version; [`Version`] corrects
//! it. Fields missing from older `LOADINFO` structs are never touched.
//! - **Panics.** A panic in your function halts the calling script instead of unwinding
//! into mIRC.
//! - **`$dllcall()`.** [`Call::is_dllcall`] tells you whether you are on a worker thread
//! and free to block.
//! - **Background threads.** mIRC unmaps the DLL when it unloads it, which crashes any
//! thread still running inside it. Threads started with [`spawn`] keep the DLL mapped
//! until they finish and are told when to stop; see [`worker`].
//! - **Talking to mIRC.** [`mirc::command`] and [`mirc::evaluate`] run commands and
//! evaluate identifiers in mIRC from any thread, safely and independently of each
//! other; see [`mirc`].
//! - **Drawing.** [`canvas`] lets Rust render frames straight into an mIRC picture window
//! with `/drawdll`, fast enough for 60 fps animation, even in the toolbar.
compile_error!;
pub use Call;
pub use ;
pub use Encoding;
pub use ;
pub use ;
pub use Version;
pub use ;
/// The full path of this DLL, as Windows reports it, such as `C:\scripts\my.dll`.
///
/// Useful for commands that name the DLL, like `/dll -u "<path>"` to unload it (a DLL can
/// unload itself from a worker started with [`spawn`]: mirust keeps it mapped until the
/// worker returns) or [`canvas::draw_command`]. Empty if Windows can't say, which doesn't
/// happen for a DLL loaded by mIRC.
///
/// ```no_run
/// let path = mirust::dll_path();
/// let _ = mirust::mirc::command(&format!("dll -u \"{path}\""));
/// ```
// Compiles the README's Rust examples as doctests, so they can't drift from the API.
;
/// Configures the DLL: how mIRC loads it, and hooks for loading and unloading.
///
/// Optional: every DLL built with mirust gets the `LoadDll` and `UnloadDll` entry points
/// automatically, using [`Config::new`]'s defaults. Use this macro, at most once per DLL,
/// to change them. The argument must be a `const` expression:
///
/// ```
/// use mirust::{Config, Host};
///
/// fn loaded(_: &Host) {}
///
/// mirust::config!(Config::new().on_load(loaded));
/// # fn main() {}
/// ```
///
/// It generates a hidden export, `__mirust_config`, that mirust's `LoadDll` looks up to
/// find the configuration. The export has the signature mIRC expects of every exported
/// function, and does nothing if a script calls it.
///
/// Every DLL also exports two reserved functions, `__mirust_deliver` and `__mirust_run`,
/// which mIRC calls to run commands returned by `$dllcall()`s (see
/// [`Response`](crate::Response#with-dllcall)). Don't export functions with these three
/// names.
/// Exports functions so mIRC can call them with `/dll`, `$dll()` and `$dllcall()`.
///
/// Each function must be callable as `fn(Call) -> impl IntoResponse`. The export takes the
/// function's name unless you give another with `as`:
///
/// ```
/// use mirust::Call;
///
/// fn version(_: Call) -> &'static str { env!("CARGO_PKG_VERSION") }
/// fn do_thing(_: Call) {}
///
/// mirust::export!(version, do_thing as "DoThing");
/// # fn main() {}
/// ```
;
}
/// Exports functions that draw into picture windows, for mIRC's `/drawdll` (7.83 and later).
///
/// Each function must be callable as `fn(`[`Draw`](canvas::Draw)`) -> impl `[`IntoUpdate`](canvas::IntoUpdate).
/// The export takes the function's name unless you give another with `as`, exactly as with
/// [`export!`]:
///
/// ```
/// use mirust::canvas::{Draw, Image, Update, rgb};
///
/// fn clear(draw: Draw) -> Update {
/// let canvas = draw.canvas();
/// let mut image = Image::new(canvas.width(), canvas.height());
/// image.fill(rgb(0, 0, 64));
/// canvas.draw(&image);
/// Update::Redraw
/// }
///
/// mirust::export_draw!(clear);
/// # fn main() {}
/// ```
///
/// Call it with `/drawdll -n @window "<path to the DLL>" clear`; [`canvas::draw_command`]
/// builds that command for you. If a script calls the export any other way, such as
/// `/dll`, there is no bitmap to draw into and it does nothing. See the [`canvas`] module.
;
}