dfhack_proto/
lib.rs

1#![warn(missing_docs)]
2#![doc = include_str!("../README.md")]
3
4/// Raw protobuf messages
5pub mod messages {
6    pub use crate::generated::messages::*;
7}
8
9/// Stubs exposing the feature of the DFHack remote API.
10///
11/// Each stub is generated from a DFHack plugin.
12/// This module is auto-generated from DFHack sources.
13pub mod stubs {
14    pub use crate::generated::stubs::*;
15}
16
17/// The `Channel` is the low-level exchange implementation.
18///
19/// It is in charge to serialize/deserialize messages, and exchange
20/// them with Dwarf Fortress. It is not meant to be used as is, but to be passed to
21/// It is analoguous to the gRPC channel.
22pub trait Channel {
23    /// Type of the errors raised by the stub.
24    ///
25    /// Defined by the channel implementation.
26    type TError;
27
28    /// Send a request to DFHack, and return its reply.
29    ///
30    /// # Errors
31    ///
32    /// The error type is defined by the channel implementation
33    ///
34    /// # Arguments
35    ///
36    /// * `plugin` - Name of the plugin implementing the request. Example: "RemoteFortressReader". Empty for core messages.
37    /// * `name` - Name of the method. Example: "GetDFVersion"
38    /// * `request` - Input of the method.
39    ///
40    /// # Returns
41    ///
42    /// A protobuf result type.
43    ///
44    fn request<TRequest: protobuf::MessageFull, TReply: protobuf::MessageFull>(
45        &mut self,
46        plugin: String,
47        name: String,
48        request: TRequest,
49    ) -> Result<TReply, Self::TError>;
50}
51
52#[cfg(feature = "reflection")]
53/// Reflection for runtime inspection of the stubs.
54pub mod reflection {
55    /// Descriptor of a remote procedure call
56    ///
57    /// These are all the needed information to make a call
58    pub struct RemoteProcedureDescriptor {
59        /// Name of the RPC
60        pub name: String,
61
62        /// Plugin implementing the RPC
63        ///
64        /// An empty string means the core API
65        pub plugin_name: String,
66
67        /// Input type
68        ///
69        /// This is the full name of the protobuf message
70        pub input_type: String,
71
72        /// Output type
73        ///
74        /// This is the full name of the protobuf message
75        pub output_type: String,
76    }
77
78    /// Ability for a stub to list its supported methods
79    ///
80    /// This is mostly useful for testing purpose.
81    pub trait StubReflection {
82        /// List the supported remote calls
83        fn list_methods() -> Vec<RemoteProcedureDescriptor>;
84    }
85}
86
87/// Generated code from this crate
88#[allow(clippy::let_unit_value)]
89mod generated {
90    pub mod messages;
91    pub mod stubs;
92}
dfhack_proto/lib.rs

dfhack_proto/
lib.rs
