Struct DomainParticipant 

pub struct DomainParticipant { /* private fields */ }

The participant.

Implementations

impl DomainParticipant

pub fn runtime(&self) -> Option<&Arc<DcpsRuntime>>

Internal access to the runtime — used by Publisher/Subscriber to create DataWriter/Reader. None when the participant is in offline mode.

pub fn domain_id(&self) -> i32

Domain id.

pub fn qos(&self) -> DomainParticipantQos

Returns a copy of the DomainParticipantQos (Spec §2.2.2.2.1.4 get_qos).

pub fn set_qos(&self, qos: DomainParticipantQos) -> Result<(), DdsError>

Sets the DomainParticipantQos (Spec §2.2.2.2.1.3 set_qos).

Errors

Currently none — the method always returns Ok(()). The spec allows IMMUTABLE_POLICY, which we do not actively produce (all policies are mutable in RC1).

pub fn register_builtin_types(&self)

Registers the 4 Spec §7.6.5 built-in types (DDS::String, DDS::KeyedString, DDS::Bytes, DDS::KeyedBytes) in the local type registry. Idempotent — a second call overwrites the entries deterministically.

Called automatically from new()/new_with_runtime(), but can also be called again after an unregister_builtin_types() disable.

pub fn unregister_builtin_types(&self)

Deletes all registered built-in types. Not called from any default path today — a test helper for disable-flag tests.

pub fn find_builtin_type(&self, name: &str) -> Option<DynamicType>

Lookup of a built-in type by spec name (Spec §7.6.5). Returns Some(DynamicType) if the name is known (registered via register_builtin_types).

pub fn registered_type_count(&self) -> usize

Number of registered built-in types. After new() == 4.

pub fn enqueue_type_lookup(&self, hash: EquivalenceHash) -> bool

Attempts to queue a TypeLookup request for an unknown EquivalenceHash. Respects backoff (5s between attempts) and at most 3 retries per hash.

Returns: true if the request was queued, false on backoff suppression or max attempts.

pub fn drain_type_lookup_requests(&self) -> Vec<(EquivalenceHash, u64)>

Drains the queued TypeLookup requests. Returns Vec<(hash, seq)>. In a production environment the caller would send the hashes via TypeLookupClient + reliable writer to the TL_SVC_REQ_WRITER endpoint.

pub fn ingest_type_lookup_reply( &self, types: Vec<(EquivalenceHash, MinimalTypeObject)>, ) -> usize

Receives a TypeLookup reply (TypeObjects per hash). Registers the TypeObjects in an internal type-registry mirror — afterwards a stalled QoS match can be retried.

Returns the number of successfully registered types.

pub fn on_remote_publication_discovered( &self, type_information_blob: Option<&[u8]>, ) -> usize

SEDP discovery hook: checks an incoming PublicationBuiltinTopicData for type hashes that cannot be resolved locally. If needed, a TypeLookup request is queued via enqueue_type_lookup.

The RPC path is live via DcpsRuntime::send_type_lookup_request on the TL_SVC_REQ_* endpoints (XTypes 1.3 §7.6.3.3.4); this method decides per hash whether a re-request is worthwhile (local registry lookup + backoff tracking).

Returns: number of unknown hashes queued (max 2 — minimal + complete).

pub fn on_remote_subscription_discovered( &self, type_information_blob: Option<&[u8]>, ) -> usize

SEDP discovery hook for SubscriptionBuiltinTopicData. Symmetric to on_remote_publication_discovered.

pub fn type_lookup_exhausted(&self, hash: EquivalenceHash) -> bool

True if MAX_ATTEMPTS has already been reached for the hash. Consulted by the match-retry path: give up eventually instead of polling forever.

pub fn create_topic<T>( &self, name: &str, qos: TopicQos, ) -> Result<Topic<T>, DdsError>

where T: DdsType,

Creates a typed topic handle. Repeated calls with the same name + type return the same handle (ref-shared).

Errors

• InconsistentPolicy if a topic with this name is already registered under a different type.
• BadParameter for an empty name.

pub fn lookup_topicdescription( &self, name: &str, ) -> Option<TopicDescriptionHandle>

Immediate local lookup of a topic by name — returns None if no local create_topic with this name has occurred. Does no discovery wait (that is find_topic). Spec reference: OMG DDS 1.4 §2.2.2.2.1.12 “lookup_topicdescription”.

pub fn find_topic( &self, name: &str, timeout: Duration, ) -> Result<TopicDescriptionHandle, DdsError>

Waits until a topic with the given name is visible via discovery (an SEDP publication or subscription) — or until timeout elapses. Spec reference: OMG DDS 1.4 §2.2.2.2.1.11 find_topic.

Returns:

• Ok(handle) with name + type name + participant, if a matching SEDP endpoint became visible during timeout. Local topics count as well (no need to wait if create_topic already ran).
• Err(Timeout) if timeout elapsed.

Errors

• DdsError::Timeout if timeout elapsed without a discovery match.
• DdsError::BadParameter for an empty name.

pub fn create_contentfilteredtopic<T>( &self, name: &str, related_topic: &Topic<T>, filter_expression: &str, filter_parameters: Vec<String>, ) -> Result<ContentFilteredTopic<T>, DdsError>

where T: DdsType,

Creates a ContentFilteredTopic as a subset of an existing Topic<T>. Spec reference: OMG DDS 1.4 §2.2.2.2.1.13 create_contentfilteredtopic.

The filter_expression is a SQL subset (see Annex B). filter_parameters are strings that replace %0, %1, … in the expression.

Errors

• BadParameter for an empty name or empty expression.
• BadParameter if the filter expression does not parse.
• BadParameter if a referenced %N parameter is not supplied in the filter_parameters vec.

pub fn create_multitopic<T>( &self, name: &str, type_name: &str, related_topic_names: Vec<String>, subscription_expression: &str, expression_parameters: Vec<String>, ) -> Result<MultiTopic<T>, DdsError>

where T: DdsType,

Creates a MultiTopic as a combining TopicDescription over 1+ underlying topics with a SQL subscription expression. Spec reference: OMG DDS 1.4 §2.2.2.2.1.15 create_multitopic (an optional spec feature).

Errors

• BadParameter for an empty name or type name.
• BadParameter if related_topic_names is empty.
• BadParameter if the subscription expression does not parse.
• BadParameter if a referenced %N parameter is not supplied in the expression_parameters vec.

pub fn delete_multitopic<T>(&self, mt: &MultiTopic<T>) -> Result<(), DdsError>

where T: DdsType,

Deletes a MultiTopic. Spec §2.2.2.2.1.16 delete_multitopic. In v1.2 it is a no-op shim with a participant match check.

Errors

BadParameter if the MultiTopic belongs to a different participant.

pub fn delete_contentfilteredtopic<T>( &self, cft: &ContentFilteredTopic<T>, ) -> Result<(), DdsError>

where T: DdsType,

Deletes a ContentFilteredTopic. Spec reference: §2.2.2.2.1.14 delete_contentfilteredtopic.

In Rust, the CFT’s lifetime handle is already covered by Drop — the underlying resources are freed once the ContentFilteredTopic<T> goes out of scope. This method exists for spec compliance of the C++ API and validates the participant match (the spec requires BadParameter if the CFT belongs to a different participant).

Errors

• BadParameter if the CFT belongs to a different participant.

pub fn create_publisher(&self, qos: PublisherQos) -> Publisher

Creates a publisher with the given QoS (the default is enough for v1.2).

pub fn create_subscriber(&self, qos: SubscriberQos) -> Subscriber

Creates a subscriber.

pub fn topics_len(&self) -> usize

Number of currently registered topics. Diagnostic API.

pub fn discovered_participants_count(&self) -> usize

Number of currently discovered remote participants via SPDP. Spec: OMG DDS 1.4 §2.2.2.2.1.7 get_discovered_participants. 0 in offline mode.

pub fn discovered_publications_count(&self) -> usize

Number of remote publications currently known in the SEDP cache. Spec: OMG DDS 1.4 §2.2.2.2.1.9 get_discovered_topics (~analogous).

pub fn discovered_subscriptions_count(&self) -> usize

Number of remote subscriptions currently known in the SEDP cache.

pub fn ignore_participant(&self, handle: InstanceHandle) -> Result<(), DdsError>

Marks a discovered remote DomainParticipant as “ignored” — all further SPDP beacons with this handle drop out of the builtin reader stream, and at the same time all SEDP endpoints belonging to the same participant prefix are also discarded (Spec §2.2.2.2.1.14).

Per spec the action is monotonic — a once-ignored participant stays ignored for the lifetime of this participant.

Errors

Currently none — the method always returns Ok(()). The spec allows OUT_OF_RESOURCES, which we do not actively produce.

pub fn ignore_topic(&self, handle: InstanceHandle) -> Result<(), DdsError>

Marks a discovered remote topic as “ignored”. Spec §2.2.2.2.1.15.

Errors

As Self::ignore_participant.

pub fn ignore_publication(&self, handle: InstanceHandle) -> Result<(), DdsError>

Marks a discovered remote publication as “ignored”. Spec §2.2.2.2.1.16.

Errors

As Self::ignore_participant.

pub fn ignore_subscription( &self, handle: InstanceHandle, ) -> Result<(), DdsError>

Marks a discovered remote subscription as “ignored”. Spec §2.2.2.2.1.17.

Errors

As Self::ignore_participant.

pub fn is_participant_ignored(&self, handle: InstanceHandle) -> bool

true if handle was marked via ignore_participant.

pub fn is_topic_ignored(&self, handle: InstanceHandle) -> bool

true if handle was marked via ignore_topic.

pub fn is_publication_ignored(&self, handle: InstanceHandle) -> bool

true if handle was marked via ignore_publication.

pub fn is_subscription_ignored(&self, handle: InstanceHandle) -> bool

true if handle was marked via ignore_subscription.

pub fn delete_contained_entities(&self) -> Result<(), DdsError>

Deletes all children held by the participant (publishers, subscribers, topics, builtin reader inboxes). Spec §2.2.2.2.1.18 — an analogous counterpart exists in Publisher/Subscriber/DataReader, which is covered here recursively.

Offline behavior:

• Topic registry cleared (local topics).
• Publisher/subscriber trackers cleared.
• Builtin-topic reader inboxes cleared (so that take() after delete_contained_entities returns an empty vec).
• No SEDP unannounce — the live behavior handles that once the runtime gets a Drop/shutdown handle. Current state: the runtime thread runs until process exit.

Errors

PreconditionNotMet if an internal mutex is poisoned.

pub fn publishers_len(&self) -> usize

Number of publishers tracked via create_publisher. Diagnostic API for tests.

pub fn subscribers_len(&self) -> usize

Number of subscribers tracked via create_subscriber.

pub fn instance_handle(&self) -> InstanceHandle

Returns this participant’s InstanceHandle. Identifies the entity to DCPS API consumers (Spec §2.2.2.1.1 get_instance_handle).

pub fn participant_handle(&self) -> InstanceHandle

This participant’s discovery-space handle: InstanceHandle::from_guid of its participant GUID.

Unlike Self::instance_handle (a local allocator counter), this is the handle the ignore filter and discovery actually key on. It is therefore the correct argument to ignore THIS participant from another one — e.g. a durability service whose sibling ingest/replay participants must ignore each other to avoid an echo loop. HANDLE_NIL when offline.

pub fn contains_entity(&self, handle: InstanceHandle) -> bool

Spec §2.2.2.2.1.10 contains_entity — true if handle belongs to this participant or one of its directly or recursively contained entities.

Included entity types:

• the participant itself
• all topics registered via create_topic
• all publishers/subscribers created via create_publisher / create_subscriber
• recursively: all DataWriter/DataReader created via Publisher::create_datawriter / Subscriber::create_datareader.

pub fn get_discovered_participants(&self) -> Vec<InstanceHandle>

Returns the InstanceHandles of all currently discovered remote participants (Spec §2.2.2.2.1.27). Empty in offline mode. Ignored participants do not appear.

pub fn get_discovered_participant_data( &self, handle: InstanceHandle, ) -> Result<ParticipantBuiltinTopicData, DdsError>

Returns the ParticipantBuiltinTopicData for a handle from get_discovered_participants (Spec §2.2.2.2.1.28).

Errors

BadParameter if handle does not reference a discovered participant (or if it was ignored).

pub fn get_discovered_topics(&self) -> Vec<InstanceHandle>

Returns the InstanceHandles of all currently discovered remote topics. Spec §2.2.2.2.1.29.

Topics are discovered indirectly via SEDP pub/sub announcements — per (topic_name, type_name) we synthesize a stable key via TopicBuiltinTopicData::synthesize_key. Ignored topics do not appear.

pub fn get_discovered_topic_data( &self, handle: InstanceHandle, ) -> Result<TopicBuiltinTopicData, DdsError>

Returns the TopicBuiltinTopicData for a handle from get_discovered_topics. Spec §2.2.2.2.1.30.

Errors

BadParameter if handle does not correspond to a discovered topic (or was ignored).

pub fn get_builtin_subscriber(&self) -> Arc<BuiltinSubscriber>

The participant’s builtin subscriber (DDS 1.4 §2.2.2.2.1.7).

Always returns the same subscriber handle (exactly one builtin subscriber per participant). It contains 4 pre-created readers for the builtin topics:

• DCPSParticipant → ParticipantBuiltinTopicData
• DCPSTopic → TopicBuiltinTopicData
• DCPSPublication → PublicationBuiltinTopicData
• DCPSSubscription → SubscriptionBuiltinTopicData

SPDP/SEDP receive internally triggers a sample insert that can be picked up via take()/read() (DDS 1.4 §2.2.5).

Example

use zerodds_dcps::*;
let participant = DomainParticipantFactory::instance()
    .create_participant_offline(0, DomainParticipantQos::default());
let bs = participant.get_builtin_subscriber();
let r = bs
    .lookup_datareader::<DcpsParticipantBuiltinTopicData>("DCPSParticipant")
    .expect("builtin reader");
// Initially empty (offline mode → no SPDP receives).
assert!(r.take().expect("take").is_empty());

pub fn set_listener( &self, listener: Option<Arc<dyn DomainParticipantListener>>, mask: u32, )

Sets the DomainParticipantListener. listener=None clears the slot. mask is the StatusMask that determines which status bits this listener consumes (Spec §2.2.4.2.3 bubble-up).

pub fn get_listener(&self) -> Option<Arc<dyn DomainParticipantListener>>

Returns the currently installed listener clone, if present. Spec §2.2.2.2.3.x get_listener.

Trait Implementations

impl Clone for DomainParticipant

fn clone(&self) -> DomainParticipant

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DomainParticipant

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Entity for DomainParticipant

type Qos = DomainParticipantQos

QoS type for this entity (e.g. DomainParticipantQos, DataWriterQos, …).

fn get_qos(&self) -> <DomainParticipant as Entity>::Qos

Returns the current QoS (clone). Spec §2.2.2.1.2 get_qos.

fn set_qos( &self, qos: <DomainParticipant as Entity>::Qos, ) -> Result<(), DdsError>

Changes the QoS. Before enable: everything allowed. After enable: only fields with “Changeable=YES” — otherwise an ImmutablePolicy error. Spec §2.2.2.1.2 set_qos.

fn enable(&self) -> Result<(), DdsError>

Enables the entity (idempotent). Spec §2.2.2.1.4 enable.

fn entity_state(&self) -> Arc<EntityState>

Internal accessor — each impl returns its Arc<EntityState>.

fn is_enabled(&self) -> bool

True if the entity is already enabled.

fn get_status_condition(&self) -> StatusCondition

StatusCondition of this entity. Spec §2.2.2.1.6 get_status_condition.

fn get_status_changes(&self) -> u32

Bitmask of the status kinds changed since the last read. Spec §2.2.2.1.5 get_status_changes.

fn get_instance_handle(&self) -> InstanceHandle

Local 64-bit identifier. Spec §2.2.2.1.7 get_instance_handle.