Expand description
String FFI
The default transport for this crate is string transport. As of BYOND 514, this is the only avalable transport.
Errors
Sometimes something may cause the parsing of arguments to fail, or returns to fail to serialize, or similar.
In these cases, the function will return an error string to BYOND. Error strings will always be structured like so:
@@ERR@@|<error class>|<error type>|<error message>
The error class is an easily machine readable string that describes the general category of error that occurred. Possible classes are:
FFI
- An error occurred while parsing arguments, serializing return values, or the function being called incorrectly -JSON
- An error occurred while parsing or serializing JSON arguments or return valuesFN
- An error occurred within the function itself being called and was returned as anErr
The error type is an easily machine readable string that describes the specific error that occurred
Error type is omitted for FN
errors, as this would require each consumer to define their own errors.
JSON Transport
parameters that use the Json
wrapper type will attempt to deserialize the parameter from JSON
into the provided type. Return types that use the Json
wrapper type will be serialized into
JSON before being sent to BYOND.
If this fails, the function will early return an error string to BYOND.
Json
requires the serde Serialize
and Deserialize
traits to be implemented for the type
See [Json](crate::str_ffi::Json)
for more information.
What’s generated
When a function is defined with #[byond_fn]
, a function with the same name is generated in a
private module with necessary trappings for calling from BYOND.
This generated function will parse the arguments from BYOND, call the original function, and
return the result to BYOND.
Example:
use byond_fn::byond_fn;
#[byond_fn]
pub fn add(arg1: u8, arg2: u8) -> u8 {
arg1 + arg2
}
will generate an adjacent module that looks like this:
mod __byond_fn_add {
#[no_mangle]
pub unsafe extern "C" fn add(
argc: ::std::os::raw::c_int,
argv: *const *const ::std::os::raw::c_char,
) -> *const ::std::os::raw::c_char {
if argc < 2i32 || argc > 2i32 {
return byond_fn::str_ffi::byond_return(
byond_fn::str_ffi::TransportError::WrongArgCount,
);
}
let args = match byond_fn::str_ffi::parse_str_args(argc, argv) {
Ok(args) => args,
Err(err) => {
return byond_fn::str_ffi::byond_return(err);
}
};
let arg1: u8 = match byond_fn::str_ffi::StrArg::from_arg(
args.get(0usize).map(|arg| *arg),
) {
Ok(arg) => arg,
Err(err) => {
return byond_fn::str_ffi::byond_return(err);
}
};
let arg2: u8 = match byond_fn::str_ffi::StrArg::from_arg(
args.get(1usize).map(|arg| *arg),
) {
Ok(arg) => arg,
Err(err) => {
return byond_fn::str_ffi::byond_return(err);
}
};
byond_fn::str_ffi::byond_return(super::add(arg1, arg2))
}
}
Modules
- This module contains easily machine parsable errors keys
Enums
Traits
- Represents a type that can be parsed from BYOND via string transport
- Represents a type that can be returned to BYOND via string transport
Functions
- A function to prep a value for returning to BYOND.
- Turns the
argc
andargv
arguments into a RustVec<&str>
.