DDS-RPC API Reference

Complete API reference for the hdds::rpc module.

ServiceClient

RPC client for sending requests to a service.

Constructor

impl ServiceClient {
    /// Create a new RPC client for a service (10s default timeout)
    pub fn new(
        participant: &Arc<Participant>,
        service_name: &str
    ) -> RpcResult<Self>;

    /// Create with custom default timeout
    pub fn with_timeout(
        participant: &Arc<Participant>,
        service_name: &str,
        default_timeout: Duration
    ) -> RpcResult<Self>;
}

Methods

impl ServiceClient {
    /// Send a request and wait for reply
    pub async fn call_raw(
        &self,
        payload: &[u8],
        timeout: Duration
    ) -> RpcResult<Vec<u8>>;

    /// Send a request with default timeout
    pub async fn call_raw_default(&self, payload: &[u8]) -> RpcResult<Vec<u8>>;

    /// Get the service name
    pub fn service_name(&self) -> &str;

    /// Shutdown the client
    pub fn shutdown(&self);
}

Example

use hdds::rpc::ServiceClient;
use std::time::Duration;

let client = ServiceClient::new(&participant, "my_service")?;

// With explicit timeout
let reply = client.call_raw(b"request", Duration::from_secs(5)).await?;

// With default timeout (10s)
let reply = client.call_raw_default(b"request").await?;

ServiceServer

RPC server for handling service requests.

Constructor

impl ServiceServer {
    /// Create a new RPC server
    pub fn new<H: RequestHandler>(
        participant: &Arc<Participant>,
        service_name: &str,
        handler: H
    ) -> RpcResult<Self>;
}

Methods

impl ServiceServer {
    /// Run the server, processing requests until shutdown
    /// This is async and blocks until shutdown
    pub async fn spin(self);

    /// Shutdown the server
    pub fn shutdown(&self);

    /// Check if running
    pub fn is_running(&self) -> bool;

    /// Get service name
    pub fn service_name(&self) -> &str;

    /// Get number of requests processed
    pub fn requests_processed(&self) -> u64;
}

RequestHandler Trait

Implement this trait to define your service logic.

pub trait RequestHandler: Send + Sync + 'static {
    /// Handle a request and return the reply payload
    fn handle(
        &self,
        request_id: SampleIdentity,
        payload: &[u8]
    ) -> Result<Vec<u8>, (RemoteExceptionCode, String)>;
}

Closures automatically implement RequestHandler:

let handler = |id: SampleIdentity, payload: &[u8]| {
    // Success
    Ok(vec![1, 2, 3])

    // Or error
    // Err((RemoteExceptionCode::InvalidArgument, "bad input".into()))
};

SampleIdentity

Unique identifier for request/reply correlation.

pub struct SampleIdentity {
    /// GUID of the DataWriter that sent the sample
    pub writer_guid: GUID,
    /// Sequence number assigned by the writer
    pub sequence_number: i64,
}

impl SampleIdentity {
    /// Create a new SampleIdentity
    pub fn new(writer_guid: GUID, sequence_number: i64) -> Self;

    /// Create a zero/null identity
    pub fn zero() -> Self;
}

RequestHeader

Header prepended to request messages.

pub struct RequestHeader {
    /// Identity of this request (for reply correlation)
    pub request_id: SampleIdentity,
    /// Optional instance handle for keyed services
    pub instance_id: SampleIdentity,
}

impl RequestHeader {
    /// Create with request ID only
    pub fn new(request_id: SampleIdentity) -> Self;

    /// Create with both request and instance IDs
    pub fn with_instance(
        request_id: SampleIdentity,
        instance_id: SampleIdentity
    ) -> Self;
}

ReplyHeader

Header prepended to reply messages.

pub struct ReplyHeader {
    /// Identity of the original request
    pub related_request_id: SampleIdentity,
    /// Exception code (0 = success)
    pub remote_exception_code: RemoteExceptionCode,
}

impl ReplyHeader {
    /// Create a successful reply
    pub fn success(related_request_id: SampleIdentity) -> Self;

    /// Create an error reply
    pub fn error(
        related_request_id: SampleIdentity,
        code: RemoteExceptionCode
    ) -> Self;

    /// Check if success
    pub fn is_success(&self) -> bool;
}

RemoteExceptionCode

Standard error codes from DDS-RPC specification.

#[repr(i32)]
pub enum RemoteExceptionCode {
    /// No error (0)
    Ok = 0,
    /// Service not found (1)
    UnsupportedService = 1,
    /// Method not found (2)
    UnsupportedMethod = 2,
    /// Invalid arguments (3)
    InvalidArgument = 3,
    /// Service unavailable (4)
    ServiceUnavailable = 4,
    /// Request timed out (5)
    Timeout = 5,
    /// Internal error (6)
    InternalError = 6,
    /// Unknown error (-1)
    Unknown = -1,
}

impl RemoteExceptionCode {
    pub fn from_i32(value: i32) -> Self;
    pub fn as_i32(self) -> i32;
}

RpcError

Errors that can occur during RPC operations.

pub enum RpcError {
    /// Failed to send request
    SendFailed(String),

    /// Request timed out
    Timeout,

    /// Remote service returned an exception
    RemoteException {
        code: RemoteExceptionCode,
        message: Option<String>,
    },

    /// Serialization error
    SerializationError(String),

    /// Deserialization error
    DeserializationError(String),

    /// Service not found
    ServiceNotFound(String),

    /// Method not found
    MethodNotFound(String),

    /// Client was shut down
    Shutdown,

    /// DDS transport error
    DdsError(hdds::dds::Error),

    /// Internal error
    Internal(String),
}

Helper Methods

impl RpcError {
    /// Create remote exception
    pub fn remote(code: RemoteExceptionCode) -> Self;

    /// Create remote exception with message
    pub fn remote_with_message(
        code: RemoteExceptionCode,
        message: impl Into<String>
    ) -> Self;

    /// Create from RemoteExceptionCode
    pub fn from_code(code: RemoteExceptionCode) -> Self;
}

RpcResult

Type alias for RPC operations.

pub type RpcResult<T> = Result<T, RpcError>;

rpc_qos()

Factory function for RPC-optimized QoS.

/// Returns QoS::reliable().keep_all().volatile()
pub fn rpc_qos() -> QoS;