Module byond_fn::str_ffi

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 values
• FN - An error occurred within the function itself being called and was returned as an Err

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

• error_keys
  This module contains easily machine parsable errors keys
• json

Enums

• FFIError
• TransportError

Traits

• StrArg
  Represents a type that can be parsed from BYOND via string transport
• StrReturn
  Represents a type that can be returned to BYOND via string transport

Functions

• byond_return
  A function to prep a value for returning to BYOND.
• parse_str_args^⚠
  Turns the argc and argv arguments into a Rust Vec<&str>.