Skip to main content

Crate mirust

Crate mirust 

Source
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/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.

Re-exports§

pub use worker::StopToken;
pub use worker::spawn;

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 / UnloadDll entry points, given to config!.
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.
WindowHandle
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::Idle unload.
UnloadReason
Why mIRC is unloading the DLL (mTimeout).

Traits§

IntoResponse
Types an exported function can return.

Functions§

buffer_capacity
Size of the data/parms buffers, 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.