OpenSplice C# API  v6.x
OpenSplice C# Data Distribution Service Data-Centric Publish-Subscribe API
DDS.DomainParticipantFactory Class Reference

The purpose of this class is to allow the creation and destruction of IDomainParticipant objects. DomainParticipantFactory itself has no factory. It is a pre-existing singleton object that can be accessed by means of the Instance property on the DomainParticipantFactory class. More...

Inheritance diagram for DDS.DomainParticipantFactory:
Inheritance graph
Collaboration diagram for DDS.DomainParticipantFactory:
Collaboration graph

Public Member Functions

IDomainParticipant CreateParticipant (DomainId domainId)
 This operation creates a new IDomainParticipant which will join the domain identified by domainId (or DDS.DomainId.Default). More...
 
IDomainParticipant CreateParticipant (DomainId domainId, IDomainParticipantListener listener, StatusKind mask)
 This operation creates a new IDomainParticipant which will join the domain identified by domainId (or DDS.DomainId.Default), and attaches the specified IDomainParticipantListener to it and uses the given communication StatusKind mask. More...
 
IDomainParticipant CreateParticipant (DomainId domainId, DomainParticipantQos qos)
 This operation creates a new IDomainParticipant which will join the domain identified by domainId (or DDS.DomainId.Default), with the desired DomainParticipantQos. More...
 
IDomainParticipant CreateParticipant (DomainId domainId, DomainParticipantQos qos, IDomainParticipantListener listener, StatusKind mask)
 This operation creates a new IDomainParticipant which will join the domain identified by domainId, with the desired DomainParticipantQos and attaches the specified IDomainParticipantListener to it and uses the given communication StatusKind mask. More...
 
ReturnCode DeleteContainedEntities ()
 This operation deletes all of the Entity objects that were created on the DomainParticipantFactory. More...
 
ReturnCode DeleteParticipant (IDomainParticipant a_participant)
 This operation deletes an IDomainParticipant. More...
 
ReturnCode DetachAllDomains (bool blockOperations, bool deleteEntities)
 This operation safely detaches the application from all domains it is currently participating in. More...
 
ReturnCode GetDefaultParticipantQos (ref DomainParticipantQos qos)
 This operation gets the default DomainParticipantQos of the DomainParticipantFactory More...
 
ReturnCode GetQos (ref DomainParticipantFactoryQos qos)
 This operation obtains the QoS settings for the DomainParticipantFactory. More...
 
IDomainParticipant LookupParticipant (DomainId domainId)
 This operation retrieves a previously created IDomainParticipant belonging to the specified domainId. More...
 
ReturnCode SetDefaultParticipantQos (DomainParticipantQos qos)
 This operation sets the default DomainParticipantQos of the DomainParticipantFactory. More...
 
ReturnCode SetQos (DomainParticipantFactoryQos qos)
 This operation replaces the existing set of QoS settings for the DomainParticipantFactory. More...
 

Properties

static DomainParticipantFactory Instance [get]
 This property is used to get the DomainParticipantFactory singleton object. More...
 

Detailed Description

The purpose of this class is to allow the creation and destruction of IDomainParticipant objects. DomainParticipantFactory itself has no factory. It is a pre-existing singleton object that can be accessed by means of the Instance property on the DomainParticipantFactory class.

Definition at line 37 of file DomainParticipantFactory.cs.

Member Function Documentation

◆ CreateParticipant() [1/4]

IDomainParticipant DDS.DomainParticipantFactory.CreateParticipant ( DomainId  domainId)
inline

This operation creates a new IDomainParticipant which will join the domain identified by domainId (or DDS.DomainId.Default).

It will use default DDS.DomainParticipantQos, a null listener and 0 mask.

See CreateParticipant for:

  • Identifying the Domain
  • Communication Status
  • Status Propagation
Parameters
domainIdThe ID of the Domain to which the IDomainParticipant is joined. This should be the ID as specified in the configuration file.
Returns
The newly created IDomainParticipant. In case of an error a null is returned.

Definition at line 144 of file DomainParticipantFactory.cs.

◆ CreateParticipant() [2/4]

IDomainParticipant DDS.DomainParticipantFactory.CreateParticipant ( DomainId  domainId,
IDomainParticipantListener  listener,
StatusKind  mask 
)
inline

This operation creates a new IDomainParticipant which will join the domain identified by domainId (or DDS.DomainId.Default), and attaches the specified IDomainParticipantListener to it and uses the given communication StatusKind mask.

It will use default DDS.DomainParticipantQos.

See CreateParticipant for:

  • Identifying the Domain
  • Communication Status
  • Status Propagation
Parameters
domainIdThe ID of the Domain to which the IDomainParticipant is joined. This should be the ID as specified in the configuration file.
listenerA IDomainParticipantListener instance which will be attached to the new IDomainParticipant. It is permitted to use null as the value of the listener: this behaves as a IDomainParticipantListener whose operations perform no action.
maskA bit-mask in which each bit enables the invocation of the IDomainParticipantListener for a certain status.
Returns
The newly created IDomainParticipant. In case of an error a null is returned.

Definition at line 174 of file DomainParticipantFactory.cs.

◆ CreateParticipant() [3/4]

IDomainParticipant DDS.DomainParticipantFactory.CreateParticipant ( DomainId  domainId,
DomainParticipantQos  qos 
)
inline

This operation creates a new IDomainParticipant which will join the domain identified by domainId (or DDS.DomainId.Default), with the desired DomainParticipantQos.

It will use a null listener and 0 mask.

See CreateParticipant for:

  • Identifying the Domain
  • Communication Status
  • Status Propagation
Parameters
domainIdThe ID of the Domain to which the IDomainParticipant is joined. This should be the ID as specified in the configuration file.
qosa DomainParticipantQos for the new IDomainParticipant. When this set of QosPolicy settings is inconsistent, no IDomainParticipant is created.
Returns
The newly created IDomainParticipant. In case of an error a null is returned.

Definition at line 203 of file DomainParticipantFactory.cs.

◆ CreateParticipant() [4/4]

IDomainParticipant DDS.DomainParticipantFactory.CreateParticipant ( DomainId  domainId,
DomainParticipantQos  qos,
IDomainParticipantListener  listener,
StatusKind  mask 
)
inline

This operation creates a new IDomainParticipant which will join the domain identified by domainId, with the desired DomainParticipantQos and attaches the specified IDomainParticipantListener to it and uses the given communication StatusKind mask.

Identifying the Domain
The IDomainParticipant will attach to the Domain that is specified by the domainId parameter. This parameter consists of an integer specified in the Id tag in the configuration file. Note that to make multiple connections to a Domain (create multiple Participants for the same Domain) within a single process, all of the Participants must use the same identification (i.e. all use the same domain Id).

The constant DDS.DomainId.Default can be used for this parameter. If this is done the value of Id tag from the configuration file specified by the environment variable called OSPL_URI will be used.

It is recommended to use this domain Id in conjunction with the OSPL_URI environment variable instead of hard-coding a domain Id into your application, since this gives you much more flexibility in the deployment phase of your product.
See also Section 1.3.2.1, The OSPL_URI environment variable, in the Deployment Guide.

Communication Status
For each communication status, the StatusChangedFlag flag is initially set to false. It becomes true whenever that communication status changes. For each communication status activated in the mask , the associated IDomainParticipantListener operation is invoked and the communication status is reset to false , as the listener implicitly accesses the status which is passed as a parameter to that operation. The fact that the status is reset prior to calling the listener means that if the application calls the Get<status_name>Status from inside the listener it will see the status already reset.

The following statuses are applicable to the IDomainParticipant

Be aware that the PublicationMatched and SubscriptionMatched statuses are not applicable when the infrastructure does not have the information available to determine connectivity. This is the case when OpenSplice is configured not to maintain discovery information in the Networking Service. (See the description for the NetworkingService/Discovery/enabled property in the Deployment Manual for more information about this subject.) In this case the operation will return NULL.

Status bits are declared as a constant and can be used by the application in an OR operation to create a tailored mask. The special constant 0 can be used to indicate that the created entity should not respond to any of its available statuses. The DDS will therefore attempt to propagate these statuses to its factory.

Status Propagation
The Data Distribution Service will trigger the most specific and relevant Listener.
In other words, in case a communication status is also activated on the Listener of a contained entity, the Listener on that contained entity is invoked instead of the IDomainParticipantListener. This means that a status change on a contained entity only invokes the IDomainParticipantListener if the contained entity itself does not handle the trigger event generated by the status change.

The statuses DataOnReaders and DataAvailable are “Read Communication Statuses” and are an exception to all other plain communication statuses: they have no corresponding status structure that can be obtained with a Get<status_name>Status operation and they are mutually exclusive. When new information becomes available to a IDataReader, the Data Distribution Service will first look in an attached and activated ISubscriberListener or IDomainParticipantListener (in that order) for the DataOnReaders. In case the DataOnReaders can not be handled, the Data Distribution Service will look in an attached and activated IDataReaderListener, ISubscriberListener or IDomainParticipantListener for the DataAvailable (in that order).

Parameters
domainIdThe ID of the Domain to which the IDomainParticipant is joined. This should be the ID as specified in the configuration file.
qosa DomainParticipantQos for the new IDomainParticipant. When this set of QosPolicy settings is inconsistent, no IDomainParticipant is created.
listenerA IDomainParticipantListener instance which will be attached to the new IDomainParticipant. It is permitted to use null as the value of the listener: this behaves as a IDomainParticipantListener whose operations perform no action.
maskA bit-mask in which each bit enables the invocation of the IDomainParticipantListener for a certain status.
Returns
The newly created IDomainParticipant. In case of an error a null is returned.

Definition at line 304 of file DomainParticipantFactory.cs.

◆ DeleteContainedEntities()

ReturnCode DDS.DomainParticipantFactory.DeleteContainedEntities ( )
inline

This operation deletes all of the Entity objects that were created on the DomainParticipantFactory.

This operation deletes all of the Entity objects that were created on the DomainParticipantFactory (it deletes all contained IDomainParticipant objects). Prior to deleting each contained Entity, this operation regressively calls the corresponding DeleteContainedEntities operation on each Participant.
In other words, this operation cleans up all Entity objects in the process.

Note
The operation will return DDS.ReturnCode PreconditionNotMet if the any of the contained entities is in a state where it cannot be deleted. This will occur, for example, if a contained IDataReader cannot be deleted because the application has called a read or take operation and has not called the corresponding ReturnLoan operation to return the loaned samples. In such cases, the operation does not roll back any entity deletions performed prior to the detection of the problem.
Returns
DDS.ReturnCode Ok - The contained Entity objects are deleted and the application may delete the DomainParticipant.
DDS.ReturnCode Error - An internal error has occurred.
DDS.ReturnCode OutOfResources - The DDS ran out of resources to complete this operation.
DDS.ReturnCode PreconditionNotMet - One or more of the contained entities are in a state where they cannot be deleted.

Definition at line 640 of file DomainParticipantFactory.cs.

◆ DeleteParticipant()

ReturnCode DDS.DomainParticipantFactory.DeleteParticipant ( IDomainParticipant  a_participant)
inline

This operation deletes an IDomainParticipant.

An IDomainParticipant cannot be deleted when it has any attached Entity objects. When the operation is called on a IDomainParticipant with existing Entity objects, the operation returns DDS.ReturnCode PreconditionNotMet.

Parameters
a_participantThe IDomainParticipant that is to be deleted.
Returns
DDS.ReturnCode Ok - The IDomainParticipant is deleted
DDS.ReturnCode Error - An internal error has occurred
DDS.ReturnCode BadParameter - The given IDomainParticipant is not valid
DDS.ReturnCode OutOfResources - The Data Distribution Service ran out of resources to complete this operation.
DDS.ReturnCode PreconditionNotMet - The IDomainParticipant contains one or more Entity objects.

Definition at line 377 of file DomainParticipantFactory.cs.

◆ DetachAllDomains()

ReturnCode DDS.DomainParticipantFactory.DetachAllDomains ( bool  blockOperations,
bool  deleteEntities 
)
inline

This operation safely detaches the application from all domains it is currently participating in.

Note
This is a proprietary OpenSplice extension.

This operation safely detaches the application from all domains it is currently participating in. When this operation has been performed successfully, the application is no longer connected to any Domain.

  • For Federated domains finishing this operation successfully means that all shared memory segments have been safely un-mapped from the application process.
  • For SingleProcess mode domains this means all services for all domains have been stopped. This allows graceful termination of the OSPL services that run as threads within the application. Graceful termination of services in this mode would for instance allow durability flushing of persistent data and networking termination announcement over the network.

When this call returns further access to all domains will be denied and it will not be possible for the application to open or re-open any DDS domain.

The behavior of the DetachAllDomains operation is determined by the blockOperations and deleteEntities parameters:

  • blockOperations: This parameter specifies if the application wants any DDS operation to be blocked or not while detaching. When true, any DDS operation called during this operation will be blocked and remain blocked forever (so also after the detach operation has completed and returns to the caller). When false, any DDS operation called during this operation may return AlreadyDeleted. Please note that a listener callback is not considered an operation in progress. Of course, if a DDS operation is called from within the listener callback, that operation will be blocked during the detaching if this attribute is set to true.
  • deleteEntities: This parameter specifies if the application wants the DDS entities created by the application to be deleted (synchronously) while detaching from the domain or not. If true, all application entities are guaranteed to be deleted when the call returns. If false, application entities will not explicitly be deleted by this operation. In case of federated mode, the splice-daemon will delete them asynchronously after this operation has returned. In case of SingleProcess mode this attribute is ignored and clean up will always be performed, as this cannot be delegated to a different process.
Note
In federated mode when the DetachAllDomains operation is called with blockOperations is false and deleteEntities is false then the DDS operations which are in progress and which are waiting for some condition to become true or waiting for an event to occur while the detach operation is performed may be blocked.
Parameters
blockOperationsIndicates whether the application wants any operations that are called while detaching to be blocked or not.
deleteEntitiesIndicates whether the application DDS entities in the 'connected' domains must be deleted synchronously during detaching.
Returns
DDS.ReturnCode Ok - The application is detached from all domains

Definition at line 722 of file DomainParticipantFactory.cs.

◆ GetDefaultParticipantQos()

ReturnCode DDS.DomainParticipantFactory.GetDefaultParticipantQos ( ref DomainParticipantQos  qos)
inline

This operation gets the default DomainParticipantQos of the DomainParticipantFactory

This operation gets the default DomainParticipantQos of the DomainParticipantFactory (that is the struct with the QosPolicy settings) which is used for newly created IDomainParticipant objects, in case no QoS is used in the CreateParticipant operation.

The application must provide the DomainParticipantQos struct in which the QosPolicy settings can be stored and provide a reference to the struct. The operation writes the default QosPolicy settings to the struct referenced to by qos.
Any settings in the struct are overwritten.
The values retrieved by this operation match the set of values specified on the last successful call to SetDefaultParticipantQos(), or, if the call was never made, the default values as specified for each QosPolicy setting.

Parameters
qosA reference to the DomainParticipantQos in which the default DomainParticipantQos for the IDomainParticipant is written
Returns
DDS.ReturnCode Ok - The new default DomainParticipantQos is set
DDS.ReturnCode Error - An internal error has occured
DDS.ReturnCode OutOfResources - The DDS ran out of resources to complete this operation

Definition at line 530 of file DomainParticipantFactory.cs.

◆ GetQos()

ReturnCode DDS.DomainParticipantFactory.GetQos ( ref DomainParticipantFactoryQos  qos)
inline

This operation obtains the QoS settings for the DomainParticipantFactory.

This operation allows access to the existing set of QoS policies of a DomainParticipantFactory on which this operation is used. This DomainParticipantFactoryQos is stored at the location pointed to by the qos parameter.

Parameters
qosA reference to the destination DomainParticipantFactoryQos, in which the Qos policies will be copied
Returns
DDS.ReturnCode Ok - The new DomainParticipantFactoryQos is set
DDS.ReturnCode Error - An internal error has occured
DDS.ReturnCode OutOfResources - The DDS ran out of resources to complete this operation

Definition at line 603 of file DomainParticipantFactory.cs.

◆ LookupParticipant()

IDomainParticipant DDS.DomainParticipantFactory.LookupParticipant ( DomainId  domainId)
inline

This operation retrieves a previously created IDomainParticipant belonging to the specified domainId.

The domainId used to search for a specific IDomainParticipant must be identical to the domainId that was used to create that specific IDomainParticipant.

If multiple IDomainParticipant entities belonging to the specified domainId exist, then the operation will return one of them. It is not specified which one.

If no IDomainParticipant was found, the operation will return NULL.

Parameters
domainIdThe ID of the Domain to which the IDomainParticipant is joined. This should be the ID as specified in the configuration file.
Returns
The retrieved IDomainParticipant. If no such IDomainParticipant is found a null is returned.

Definition at line 434 of file DomainParticipantFactory.cs.

◆ SetDefaultParticipantQos()

ReturnCode DDS.DomainParticipantFactory.SetDefaultParticipantQos ( DomainParticipantQos  qos)
inline

This operation sets the default DomainParticipantQos of the DomainParticipantFactory.

This operation sets the default DomainParticipantQos of the DomainParticipantFactory (that is the struct with the QosPolicy settings) which is used for newly created IDomainParticipant objects, in case no QoS was provided in the CreateParticipant operation.

The DomainParticipantQos is always self consistent, because its policies do not depend on each other.
This means this operation never returns the ReturnCode InconsistentPolicy.

The values set by this operation are returned by GetDefaultParticipantQos().

Parameters
qosThe DomainParticipantQos which contains the new default DomainParticipantQos for the newly created DomainParticipants
Returns
DDS.ReturnCode Ok - The new default DomainParticipantQos is set
DDS.ReturnCode Error - An internal error has occured
DDS.ReturnCode OutOfResources - The DDS ran out of resources to complete this operation

Definition at line 472 of file DomainParticipantFactory.cs.

◆ SetQos()

ReturnCode DDS.DomainParticipantFactory.SetQos ( DomainParticipantFactoryQos  qos)
inline

This operation replaces the existing set of QoS settings for the DomainParticipantFactory.

This operation replaces the existing set of QosPolicy settings for a DomainParticipantFactory. The parameter qos must contain the struct with the QosPolicy settings.

The set of QosPolicy settings specified by the qos parameter are applied on top of the existing QoS, replacing the values of any policies previously set (provided, the operation returned Ok).

Parameters
qosThe new set of Qos policy settings for the DomainParticipantFactory
Returns
DDS.ReturnCode Ok - The new DomainParticipantFactoryQos is set
DDS.ReturnCode Error - An internal error has occured
DDS.ReturnCode OutOfResources - The DDS ran out of resources to complete this operation

Definition at line 580 of file DomainParticipantFactory.cs.

Property Documentation

◆ Instance

DomainParticipantFactory DDS.DomainParticipantFactory.Instance
staticget

This property is used to get the DomainParticipantFactory singleton object.

The operation is idempotent, that is, it can be called multiple times without side-effects and it returns the same DomainParticipantFactory instance.

factory = DomainParticipantFactory.Instance;
Returns
DomainParticipantFactory singleton

Definition at line 101 of file DomainParticipantFactory.cs.


The documentation for this class was generated from the following file: