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
//! 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`].
compile_error!;
pub use Call;
pub use ;
pub use Encoding;
pub use ;
pub use ;
pub use Version;
pub use ;
// 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() {}
/// ```
;
}