![]() |
OpenSplice C# API
v6.x
OpenSplice C# Data Distribution Service Data-Centric Publish-Subscribe API
|
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...
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... | |
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.
|
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:
domainId | The ID of the Domain to which the IDomainParticipant is joined. This should be the ID as specified in the configuration file. |
Definition at line 144 of file DomainParticipantFactory.cs.
|
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:
domainId | The ID of the Domain to which the IDomainParticipant is joined. This should be the ID as specified in the configuration file. |
listener | A 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. |
mask | A bit-mask in which each bit enables the invocation of the IDomainParticipantListener for a certain status. |
Definition at line 174 of file DomainParticipantFactory.cs.
|
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:
domainId | The ID of the Domain to which the IDomainParticipant is joined. This should be the ID as specified in the configuration file. |
qos | a DomainParticipantQos for the new IDomainParticipant. When this set of QosPolicy settings is inconsistent, no IDomainParticipant is created. |
Definition at line 203 of file DomainParticipantFactory.cs.
|
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).
domainId | The ID of the Domain to which the IDomainParticipant is joined. This should be the ID as specified in the configuration file. |
qos | a DomainParticipantQos for the new IDomainParticipant. When this set of QosPolicy settings is inconsistent, no IDomainParticipant is created. |
listener | A 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. |
mask | A bit-mask in which each bit enables the invocation of the IDomainParticipantListener for a certain status. |
Definition at line 304 of file DomainParticipantFactory.cs.
|
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.
Definition at line 640 of file DomainParticipantFactory.cs.
|
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.
a_participant | The IDomainParticipant that is to be deleted. |
Definition at line 377 of file DomainParticipantFactory.cs.
|
inline |
This operation safely detaches the application from all domains it is currently participating in.
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.
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 | Indicates whether the application wants any operations that are called while detaching to be blocked or not. |
deleteEntities | Indicates whether the application DDS entities in the 'connected' domains must be deleted synchronously during detaching. |
Definition at line 722 of file DomainParticipantFactory.cs.
|
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.
qos | A reference to the DomainParticipantQos in which the default DomainParticipantQos for the IDomainParticipant is written |
Definition at line 530 of file DomainParticipantFactory.cs.
|
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.
qos | A reference to the destination DomainParticipantFactoryQos, in which the Qos policies will be copied |
Definition at line 603 of file DomainParticipantFactory.cs.
|
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.
domainId | The ID of the Domain to which the IDomainParticipant is joined. This should be the ID as specified in the configuration file. |
Definition at line 434 of file DomainParticipantFactory.cs.
|
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().
qos | The DomainParticipantQos which contains the new default DomainParticipantQos for the newly created DomainParticipants |
Definition at line 472 of file DomainParticipantFactory.cs.
|
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).
qos | The new set of Qos policy settings for the DomainParticipantFactory |
Definition at line 580 of file DomainParticipantFactory.cs.
|
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.
Definition at line 101 of file DomainParticipantFactory.cs.