samp_sdk/omp/

component_api.rs

//! High-level API for Open Multiplayer server components.
//!
//! The raw pointer returned by `server::query_component` is opaque — it only
//! lets you check presence, with no way to interact with the component's
//! vtable. This module defines the [`OmpComponentHandle`] trait that specific
//! types (`PawnComponent`, `TimersComponent`, etc.) implement to provide:
//!
//! - The component's known `UID` (associated constant)
//! - Safe construction from the raw pointer
//! - Access to shared methods (`componentName`, `componentVersion`) via the
//!   generic utility functions in this module
//!
//! Plugins implementing their own external component declare the trait with
//! the UID generated by the SDK.

use super::server::ServerComponent;
use super::types::{SemanticVersion, StringView, UID};
use std::ptr::NonNull;

/// Trait implemented by typed wrappers for Open Multiplayer components.
///
/// Each implementation:
/// - Provides the component's constant `UID` in [`UID`].
/// - Constructs itself from a [`NonNull<ServerComponent>`] returned by
///   [`samp_sdk::omp::server::query_component`].
/// - Exposes the raw pointer via [`as_raw`].
///
/// [`as_raw`]: OmpComponentHandle::as_raw
/// [`samp_sdk::omp::server::query_component`]: super::server::query_component
pub trait OmpComponentHandle: Sized + Copy {
    /// Component UID — known at compile time.
    const UID: UID;

    /// Builds the wrapper from the pointer returned by `query_component`.
    ///
    /// # Safety
    /// `ptr` must have been obtained via `query_component(_, Self::UID)` and the
    /// server must keep the component alive while the wrapper is used.
    unsafe fn from_raw(ptr: NonNull<ServerComponent>) -> Self;

    /// Returns the raw component pointer.
    fn as_raw(&self) -> NonNull<ServerComponent>;
}

/// Slot of `componentName()` in the `IComponent` vtable.
///
/// Itanium emits two destructor slots (D1 + D0) where MSVC emits a single
/// scalar deleting one, which shifts every method after it by one. Both
/// numbers are confirmed against the official `Timers.so` / `Timers.dll`.
#[cfg(not(target_env = "msvc"))]
const SLOT_COMPONENT_NAME: usize = 7;

#[cfg(target_env = "msvc")]
const SLOT_COMPONENT_NAME: usize = 6;

/// Slot of `componentVersion()` in the `IComponent` vtable (same shift as
/// [`SLOT_COMPONENT_NAME`]).
#[cfg(not(target_env = "msvc"))]
const SLOT_COMPONENT_VERSION: usize = 9;

#[cfg(target_env = "msvc")]
const SLOT_COMPONENT_VERSION: usize = 8;

/// Signature of `componentName()`. The Itanium ABI returns the 8-byte
/// `StringView` in registers; MSVC returns it through a hidden pointer.
#[cfg(not(target_env = "msvc"))]
type ComponentNameFn = unsafe extern "C" fn(*mut ServerComponent) -> StringView;

#[cfg(target_env = "msvc")]
type ComponentNameFn =
    unsafe extern "thiscall" fn(*mut ServerComponent, *mut StringView) -> *mut StringView;

/// Signature of `componentVersion()`. Same split as `componentName`: registers
/// under Itanium, hidden pointer under MSVC.
#[cfg(not(target_env = "msvc"))]
type ComponentVersionFn = unsafe extern "C" fn(*mut ServerComponent) -> SemanticVersion;

#[cfg(target_env = "msvc")]
type ComponentVersionFn =
    unsafe extern "thiscall" fn(*mut ServerComponent, *mut SemanticVersion) -> *mut SemanticVersion;

/// Reads the component name by calling `componentName()` ([`SLOT_COMPONENT_NAME`] of the `IComponent` vtable).
///
/// Returns a `String` with the UTF-8 name (copied — does not retain pointers from the component).
/// `None` if the component or vtable are null, the slot is empty, the returned
/// `StringView` is invalid, or the bytes are not valid UTF-8.
pub fn component_name<T: OmpComponentHandle>(c: &T) -> Option<String> {
    let raw = c.as_raw().as_ptr();
    // The primary vtable (IComponent) is at offset 0 of the object.
    let (_, slot) = unsafe {
        super::vtable::secondary_call_target_ptr(raw.cast::<u8>(), 0, SLOT_COMPONENT_NAME)?
    };
    let f: ComponentNameFn = unsafe { std::mem::transmute(slot) };

    // The Itanium ABI hands back a struct this small in EAX:EDX; MSVC writes it
    // through a hidden pointer the caller supplies. Getting this backwards
    // reads whatever the registers happened to hold — or crashes the server, as
    // it did when the same mistake was made for `IPlayer::getName`.
    #[cfg(not(target_env = "msvc"))]
    let sv = unsafe { f(raw) };

    #[cfg(target_env = "msvc")]
    let sv = {
        let mut sv = StringView {
            data: std::ptr::null(),
            len: 0,
        };
        unsafe { f(raw, &raw mut sv) };
        sv
    };
    if sv.data.is_null() || sv.len == 0 {
        return None;
    }
    let bytes = unsafe { std::slice::from_raw_parts(sv.data, sv.len) };
    std::str::from_utf8(bytes).ok().map(String::from)
}

/// Reads the component version by calling `componentVersion()` ([`SLOT_COMPONENT_VERSION`] of the `IComponent` vtable).
///
/// Official Open Multiplayer components return the server version (e.g. `1.5.8.3079`).
/// `None` if the component or vtable are null or the slot is empty.
pub fn component_version<T: OmpComponentHandle>(c: &T) -> Option<SemanticVersion> {
    let raw = c.as_raw().as_ptr();
    let (_, slot) = unsafe {
        super::vtable::secondary_call_target_ptr(raw.cast::<u8>(), 0, SLOT_COMPONENT_VERSION)?
    };
    let f: ComponentVersionFn = unsafe { std::mem::transmute(slot) };

    #[cfg(not(target_env = "msvc"))]
    let version = unsafe { f(raw) };

    #[cfg(target_env = "msvc")]
    let version = {
        let mut version = SemanticVersion::new(0, 0, 0);
        unsafe { f(raw, &raw mut version) };
        version
    };
    Some(version)
}

#[cfg(test)]
mod tests {
    //! Smoke tests for `component_name` and `component_version`.
    //!
    //! Sets up a fake `ServerComponent` with a mock vtable at the name
    //! and version slots for the target ABI. Covers typed wrappers via a test type that implements
    //! [`OmpComponentHandle`].

    use super::*;
    use crate::omp::vtable::MockTable;
    use std::sync::Mutex;

    static TEST_LOCK: Mutex<()> = Mutex::new(());

    // Mock vtable: 16 slots (minimum size of IComponent MSVC).
    // Only the name and version slots are populated.
    static MOCK_VTABLE: std::sync::OnceLock<MockTable<16>> = std::sync::OnceLock::new();

    fn mock_vtable() -> &'static [*const (); 16] {
        &MOCK_VTABLE
            .get_or_init(|| {
                let mut v = [unused as *const (); 16];
                v[SLOT_COMPONENT_NAME] = mock_name as *const ();
                v[SLOT_COMPONENT_VERSION] = mock_version as *const ();
                MockTable(v)
            })
            .0
    }

    // The mock functions MUST match the calling convention declared in
    // `ComponentNameFn` / `ComponentVersionFn` (cfg-gated by ABI). Declaring
    // them `extern "C"` on MSVC causes a STATUS_ACCESS_VIOLATION because the
    // call site is built for `thiscall` (this in ECX, callee cleans the
    // stack with `ret 4`) and reads `out` from the wrong stack slot.

    #[cfg(not(target_env = "msvc"))]
    unsafe extern "C" fn unused() {}
    #[cfg(target_env = "msvc")]
    unsafe extern "thiscall" fn unused() {}

    static MOCK_NAME_BYTES: &[u8] = b"test-comp";

    #[cfg(not(target_env = "msvc"))]
    // Mirrors the real convention: Itanium returns the struct in registers.
    unsafe extern "C" fn mock_name(_this: *mut ServerComponent) -> StringView {
        StringView {
            data: MOCK_NAME_BYTES.as_ptr(),
            len: MOCK_NAME_BYTES.len(),
        }
    }

    #[cfg(target_env = "msvc")]
    unsafe extern "thiscall" fn mock_name(
        _this: *mut ServerComponent,
        out: *mut StringView,
    ) -> *mut StringView {
        unsafe {
            *out = StringView {
                data: MOCK_NAME_BYTES.as_ptr(),
                len: MOCK_NAME_BYTES.len(),
            };
        }
        out
    }

    #[cfg(not(target_env = "msvc"))]
    unsafe extern "C" fn mock_version(_this: *mut ServerComponent) -> SemanticVersion {
        SemanticVersion::new(2, 7, 3)
    }

    #[cfg(target_env = "msvc")]
    unsafe extern "thiscall" fn mock_version(
        _this: *mut ServerComponent,
        out: *mut SemanticVersion,
    ) -> *mut SemanticVersion {
        unsafe {
            *out = SemanticVersion::new(2, 7, 3);
        }
        out
    }

    /// Dummy type implementing `OmpComponentHandle` only for the test.
    #[derive(Debug, Clone, Copy)]
    struct DummyComponent {
        ptr: NonNull<ServerComponent>,
    }

    impl OmpComponentHandle for DummyComponent {
        const UID: UID = 0xDEAD_BEEF_CAFE_BABE;
        unsafe fn from_raw(ptr: NonNull<ServerComponent>) -> Self {
            Self { ptr }
        }
        fn as_raw(&self) -> NonNull<ServerComponent> {
            self.ptr
        }
    }

    /// Builds a value simulating `ServerComponent`: vptr at offset 0.
    /// The caller must bind to a local to get a stable address.
    fn make_mock_component() -> *const *const () {
        mock_vtable().as_ptr()
    }

    /// Slots verified against the official `Timers.so` (Itanium) and
    /// `Timers.dll` (MSVC) vtables of open.mp 1.5.8.3079.
    #[test]
    fn component_slots_match_the_official_binaries() {
        #[cfg(not(target_env = "msvc"))]
        {
            assert_eq!(SLOT_COMPONENT_NAME, 7);
            assert_eq!(SLOT_COMPONENT_VERSION, 9);
        }
        #[cfg(target_env = "msvc")]
        {
            assert_eq!(SLOT_COMPONENT_NAME, 6);
            assert_eq!(SLOT_COMPONENT_VERSION, 8);
        }
    }

    #[test]
    fn component_name_reads_slot_6_and_returns_string() {
        let _g = TEST_LOCK.lock().unwrap();
        let buf = make_mock_component();
        let raw = (&raw const buf).cast::<ServerComponent>().cast_mut();
        let nn = NonNull::new(raw).unwrap();
        let comp = unsafe { DummyComponent::from_raw(nn) };

        let name = component_name(&comp);
        assert_eq!(name.as_deref(), Some("test-comp"));
    }

    #[test]
    fn component_version_reads_slot_8_and_returns_semver() {
        let _g = TEST_LOCK.lock().unwrap();
        let buf = make_mock_component();
        let raw = (&raw const buf).cast::<ServerComponent>().cast_mut();
        let nn = NonNull::new(raw).unwrap();
        let comp = unsafe { DummyComponent::from_raw(nn) };

        let v = component_version(&comp).unwrap();
        assert_eq!((v.major, v.minor, v.patch), (2, 7, 3));
    }

    #[test]
    fn dummy_component_uid_is_consistent() {
        assert_eq!(DummyComponent::UID, 0xDEAD_BEEF_CAFE_BABE);
    }
}