Crate vibha [−] [src]
Defines the types and helpers for binary/library communication.
The general idea is that the user will run a driver program which calls
game_init
to get a handle, and then gets lines from the user and passes
them to game_process_line
, and prints the output. At some point the
driving program might try to exit cleanly, and if so it'll call game_drop
.
Of course, the driving program might suddenly die at any moment without
game_drop
ever being called, so I wouldn't rely on that happening.
Note that all of the interchange types are fully compatible with the C ABI, so you don't have to use Rust if you don't want to. As long as you follow the types you can write your DLL and/or driving program in any language you like.
To be loaded properly, your DLL should have one function of each function type given here, named in snake_case without the "Fn" part at the end:
GameInitFn
:game_init
GameProcessLineFn
:game_process_line
GameDropFn
:game_drop
Building a game DLL with cargo
First, be sure to mark your functions with #[no_mangle]
and pub
. You
must also have "cdylib" as one of your crate-type
values for your crate's
library portion. If you want cargo test
to work properly, you'll need
"rlib" as well. It'll look something like this:
[lib]
name = "vibha"
path = "src/lib.rs"
crate-type = ["rlib", "cdylib"]
You can easily ensure that your functions have the correct type at compile
time with a simple set of const
declarations.
A "complete" example might look something like this.
extern crate vibha; use vibha::*; use std::io::Write; use std::os::raw::c_void; struct GameState { world_seed: u64, call_count: u64, } #[no_mangle] pub unsafe extern "C" fn game_init(world_seed: u64) -> *mut c_void { Box::into_raw(Box::new(GameState { world_seed, call_count: 0 })) as *mut c_void } #[no_mangle] pub unsafe extern "C" fn game_process_line(handle: *mut c_void, line: *const u8, line_len: usize, mut buf: *mut u8, buf_len: usize) -> usize { if handle.is_null() || line.is_null() || buf.is_null() { return 0; } let user_line = ffi_recover_str(&line, line_len); let mut out_buffer = ffi_recover_out_buffer(&mut buf, buf_len); let game_state: &mut GameState = (handle as *mut GameState).as_mut().expect("game session was null!"); // do something silly just so we can see an effect game_state.call_count += 1; if user_line.len() > 0 { write!(out_buffer, "{}: {}", game_state.call_count, user_line).ok(); } else { write!(out_buffer, "{}: {}", game_state.call_count, game_state.world_seed).ok(); } out_buffer.position() as usize } #[no_mangle] pub unsafe extern "C" fn game_drop(handle: *mut c_void) { Box::from_raw(handle as *mut GameState); } #[allow(dead_code)] const GAME_INIT_CONST: GameInitFn = game_init; #[allow(dead_code)] const GAME_PROCESS_LINE_CONST: GameProcessLineFn = game_process_line; #[allow(dead_code)] const GAME_DROP_CONST: GameDropFn = game_drop;
Structs
VibhaVersion |
Allows you to specify a protocol version. |
Enums
ModalSlice |
Wraps a string slice with a "mode" tag. |
Constants
ANSI_COLOR_AVAILABLE_HEADER |
Signals that the driver supports ANSI color outputs. |
BACKGROUND_BLACK |
Makes the background black until the end of this output |
BACKGROUND_BLUE |
Makes the background blue until the end of this output |
BACKGROUND_CYAN |
Makes the background cyan until the end of this output |
BACKGROUND_GREEN |
Makes the background green until the end of this output |
BACKGROUND_MAGENTA |
Makes the background magenta until the end of this output |
BACKGROUND_RED |
Makes the background red until the end of this output |
BACKGROUND_WHITE |
Makes the background white until the end of this output |
BACKGROUND_YELLOW |
Makes the background yellow until the end of this output |
FOREGROUND_BLACK |
Makes the foreground black until the end of this output |
FOREGROUND_BLUE |
Makes the foreground blue until the end of this output |
FOREGROUND_CYAN |
Makes the foreground cyan until the end of this output |
FOREGROUND_GREEN |
Makes the foreground green until the end of this output |
FOREGROUND_MAGENTA |
Makes the foreground magenta until the end of this output |
FOREGROUND_RED |
Makes the foreground red until the end of this output |
FOREGROUND_WHITE |
Makes the foreground white until the end of this output |
FOREGROUND_YELLOW |
Makes the foreground yellow until the end of this output |
INTRO_HEADER |
Requests the game to display its introduction. |
VIBHA_VERSION_PREFIX |
The prefix for the formatted vibha version header. |
Functions
ffi_recover_out_buffer⚠ |
Converts the pointer and len for the output buffer into a rusty form. |
ffi_recover_str⚠ |
Converts the const pointer and len for the user's input line into a rusty form. |
filter_text_only |
Filters the results of |
mode_split_str |
Breaks up a |
Type Definitions
GameDropFn |
Frees up the game session data. |
GameInitFn |
Initializes a game session. |
GameProcessLineFn |
Processes a single line of user input. |