Expand description
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);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/parmsbuffers have grown from 900 bytes to over 10 KB, andmByteswas 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;
Versioncorrects it. Fields missing from olderLOADINFOstructs are never touched. - Panics. A panic in your function halts the calling script instead of unwinding into mIRC.
$dllcall().Call::is_dllcalltells 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
spawnkeep the DLL mapped until they finish and are told when to stop; seeworker. - Talking to mIRC.
mirc::commandandmirc::evaluaterun commands and evaluate identifiers in mIRC from any thread, safely and independently of each other; seemirc. - Drawing.
canvaslets Rust render frames straight into an mIRC picture window with/drawdll, fast enough for 60 fps animation, even in the toolbar.
Re-exports§
Modules§
- canvas
- Draw into mIRC picture windows from Rust, with
/drawdll(mIRC 7.83 and later). - mirc
- Running commands and evaluating identifiers in mIRC, from any thread.
- worker
- Background threads that survive mIRC unloading the DLL, and a grace period at exit.
Macros§
- config
- Configures the DLL: how mIRC loads it, and hooks for loading and unloading.
- export
- Exports functions so mIRC can call them with
/dll,$dll()and$dllcall(). - export_
draw - Exports functions that draw into picture windows, for mIRC’s
/drawdll(7.83 and later).
Structs§
- Call
- One invocation of an exported function by
/dll,$dll()or$dllcall(). - Config
- Settings for the
LoadDll/UnloadDllentry points, given toconfig!. - Host
- What mirust knows about the client that loaded the DLL: the equivalent of mIRC’s
LOADINFO, valid on every version. - Version
- An mIRC version number, such as
7.85. - Window
Handle - A window handle (
HWND) passed in by mIRC.
Enums§
- Client
- Which client loaded the DLL: mIRC, or AdiIRC, the only other client that loads mIRC DLLs.
- Encoding
- How mIRC encodes the strings it exchanges with the DLL.
- Response
- What mIRC should do after an exported function returns.
- Unload
- Answer to an
UnloadReason::Idleunload. - Unload
Reason - Why mIRC is unloading the DLL (
mTimeout).
Traits§
- Into
Response - Types an exported function can return.
Functions§
- buffer_
capacity - Size of the
data/parmsbuffers, in code units including the NUL terminator. - dll_
path - The full path of this DLL, as Windows reports it, such as
C:\scripts\my.dll. - host
- The client that loaded this DLL.