 |
OpenSplice C# API
v6.x
OpenSplice C# Data Distribution Service Data-Centric Publish-Subscribe API
|
|
OpenSplice C# API
v6.x
OpenSplice C# Data Distribution Service Data-Centric Publish-Subscribe API
|
The IPublisher acts on behalf of one or more IDataWriter objects that belong to it. When it is informed of a change to the data associated with one of its IDataWriter objects, it decides when it is appropriate to actually process the sample-update message. In making this decision, it considers the PublisherQos and the DataWriterQos. More...
Public Member Functions | |
| ReturnCode | BeginCoherentChanges () |
| This operation requests that the application will begin a ‘coherent set’ of modifications using IDataWriter objects attached to this IPublisher. The ‘coherent set’ will be completed by a matching call to IPublisher.EndCoherentChanges. More... | |
| ReturnCode | CopyFromTopicQos (ref DataWriterQos dataWriterQos, TopicQos topicQos) |
| This operation will copy policies in topicQos to the corresponding policies in DataWriterQos. More... | |
| IDataWriter | CreateDataWriter (ITopic topic) |
| This operations behaves similarly to the most complete operation, and it substitutes default values for the missing parameters. Default for QoS for QoS parameters, null for listeners and 0 mask for listener parameters. More... | |
| IDataWriter | CreateDataWriter (ITopic topic, IDataWriterListener listener, StatusKind mask) |
| This operations behaves similarly to the most complete operation, and it substitutes default values for the missing parameters. Default for QoS for QoS parameters. More... | |
| IDataWriter | CreateDataWriter (ITopic topic, DataWriterQos qos) |
| This operations behaves similarly to the most complete operation, and it substitutes default values for the missing parameters. Default null for listeners and 0 mask for listener parameters. More... | |
| IDataWriter | CreateDataWriter (ITopic topic, DataWriterQos qos, IDataWriterListener listener, StatusKind mask) |
| This operation creates a IDataWriter with the desired DataWriterQos, for the desired ITopic and attaches the optionally specified IDataWriterListener to it. More... | |
| ReturnCode | DeleteContainedEntities () |
| This operation deletes all the IDataWriter objects that were created by means of one of the CreateDataWriter operations on the IPublisher. More... | |
| ReturnCode | DeleteDataWriter (IDataWriter dataWriter) |
| This operation deletes a IDataWriter that belongs to the IPublisher. More... | |
| ReturnCode | EndCoherentChanges () |
| This operation terminates the ‘coherent set’ initiated by the matching call to IPublisher.BeginCoherentChanges. More... | |
| ReturnCode | GetDefaultDataWriterQos (ref DataWriterQos qos) |
| This operation gets the default DataWriterQos of the IPublisher. More... | |
| IDomainParticipant | GetParticipant () |
| This operation returns the IDomainParticipant associated with the IPublisher. More... | |
| ReturnCode | GetQos (ref PublisherQos qos) |
| This operation allows access to the existing set of QoS policies for a IPublisher. More... | |
| IDataWriter | LookupDataWriter (string topicName) |
| This operation returns a previously created IDataWriter belonging to the IPublisher which is attached to a ITopic with the matching topicName. More... | |
| ReturnCode | ResumePublications () |
| This operation resumes a previously suspended publication. More... | |
| ReturnCode | SetDefaultDataWriterQos (DataWriterQos qos) |
| This operation sets the default DataWriterQos of the IPublisher. More... | |
| ReturnCode | SetListener (IPublisherListener listener, StatusKind mask) |
| This operation attaches a PublisherListener to the IPublisher. More... | |
| ReturnCode | SetQos (PublisherQos qos) |
| This operation replaces the existing set of QosPolicy settings for a IPublisher. More... | |
| ReturnCode | SuspendPublications () |
| This operation will suspend the dissemination of the publications by all contained IDataWriter objects. More... | |
| ReturnCode | WaitForAcknowledgments (Duration maxWait) |
| This operation blocks the calling thread until either all data written by all contained DataWriters is acknowledged by the local infrastructure, or until the duration specified by maxWait parameter elapses, whichever happens first. More... | |
 Public Member Functions inherited from DDS.IEntity | |
| ReturnCode | Enable () |
| This operation enables the IEntity on which it is being called when the IEntity was created with the EntityFactoryQosPolicy set to false. More... | |
Properties | |
| IPublisherListener | Listener [get] |
| This property returns the PublisherListener currently attached to the IPublisher. More... | |
| Properties inherited from DDS.IEntity | |
| InstanceHandle | InstanceHandle [get] |
| This operation returns the InstanceHandle of the builtin topic sample that represents the specified IEntity. More... | |
| StatusKind | StatusChanges [get] |
| This operation returns a mask with the communication statuses in the IEntity that are triggered. More... | |
| IStatusCondition | StatusCondition [get] |
| This property allows access to the IStatusCondition associated with the IEntity. More... | |
The IPublisher acts on behalf of one or more IDataWriter objects that belong to it. When it is informed of a change to the data associated with one of its IDataWriter objects, it decides when it is appropriate to actually process the sample-update message. In making this decision, it considers the PublisherQos and the DataWriterQos.
Definition at line 2624 of file DdsDcpsInterfaces.cs.
| ReturnCode DDS.IPublisher.BeginCoherentChanges | ( | ) |
This operation requests that the application will begin a ‘coherent set’ of modifications using IDataWriter objects attached to this IPublisher. The ‘coherent set’ will be completed by a matching call to IPublisher.EndCoherentChanges.
A ‘coherent set’ is a set of modifications that must be propagated in such a way that they are interpreted at the receivers’ side as a consistent set of modifications; that is, the receiver will only be able to access the data after all the modifications in the set are available at the receiver end. A precondition for making coherent changes is that the PresentationQos of the IPublisher has its CoherentAccess attribute set to true. If this is not the case, the IPublisher will not accept any coherent start requests and return DDS.ReturnCode PreconditionNotMet.
A connectivity change may occur in the middle of a set of coherent changes; for example, the set of partitions used by the IPublisher or one of its connected ISubscribers may change, a late-joining IDataReader may appear on the network, or a communication failure may occur. In the event that such a change prevents an entity from receiving the entire set of coherent changes, that entity must behave as if it had received none of the set. These calls can be nested. In that case, the coherent set terminates only with the last call to IPublisher.EndCoherentChanges.
The support for ‘coherent changes’ enables a publishing application to change the value of several data-instances that could belong to the same or different topics and have those changes be seen ‘atomically’ by the readers. This is useful in cases where the values are inter-related (for example, if there are two data-instances representing the ‘altitude’ and ‘velocity vector’ of the same aircraft and both are changed, it may be useful to communicate those values in a way the reader can see both together; otherwise, it may e.g., erroneously interpret that the aircraft is on a collision course).
| ReturnCode DDS.IPublisher.CopyFromTopicQos | ( | ref DataWriterQos | dataWriterQos, |
| TopicQos | topicQos | ||
| ) |
This operation will copy policies in topicQos to the corresponding policies in DataWriterQos.
This operation will copy the QosPolicy settings in topicQos to the corresponding QosPolicy settings in datawriterQos (replacing the values in DataWriterQos, if present). This will only apply to the common QosPolicy settings in each "IEntity" Qos. This is a convenience operation, useful in combination with the operations GetDefaultDataWriterQos and ITopic.GetQos. The operation CopyFromTopicQos can be used to merge the IDataWriter default QosPolicy settings with the corresponding ones on the TopicQos. The resulting DataWriterQos can then be used to create a new IDataWriter, or set its DataWriterQos. This operation does not check the resulting dataWriterQos for consistency. This is because the merged DataWriterQos may not be the final one, as the application can still modify some QosPolicy settings prior to applying the DataWriterQos to the IDataWriter.
| dataWriterQos | The destination DataWriterQos struct to which the QosPolicy settings should be copied. |
| topicQos | The source TopicQos struct, which should be copied. |
| IDataWriter DDS.IPublisher.CreateDataWriter | ( | ITopic | topic | ) |
This operations behaves similarly to the most complete operation, and it substitutes default values for the missing parameters. Default for QoS for QoS parameters, null for listeners and 0 mask for listener parameters.
| topic | The topic for which the IDataWriter is created. |
| IDataWriter DDS.IPublisher.CreateDataWriter | ( | ITopic | topic, |
| IDataWriterListener | listener, | ||
| StatusKind | mask | ||
| ) |
This operations behaves similarly to the most complete operation, and it substitutes default values for the missing parameters. Default for QoS for QoS parameters.
| topic | The topic for which the IDataWriter is created. |
| listener | The IDataWriterListener instance which will be attached to the new IDataWriter. It is permitted to use null as the value of the listener: this behaves as a IDataWriterListener whose operations perform no action. |
| mask | bit mask in which each bit enables the invocation of the IDataWriterListener for a certain status. |
| IDataWriter DDS.IPublisher.CreateDataWriter | ( | ITopic | topic, |
| DataWriterQos | qos | ||
| ) |
This operations behaves similarly to the most complete operation, and it substitutes default values for the missing parameters. Default null for listeners and 0 mask for listener parameters.
| topic | The topic for which the IDataWriter is created. |
| qos | The DataWriterQos for the new IDataWriter. In case these settings are not self consistent, no IDataWriter is created. |
| IDataWriter DDS.IPublisher.CreateDataWriter | ( | ITopic | topic, |
| DataWriterQos | qos, | ||
| IDataWriterListener | listener, | ||
| StatusKind | mask | ||
| ) |
This operation creates a IDataWriter with the desired DataWriterQos, for the desired ITopic and attaches the optionally specified IDataWriterListener to it.
This operation creates a IDataWriter with the desired DataWriterQos, for the desired ITopic and attaches the optionally specified IDataWriterListener to it. The returned IDataWriter is attached (and belongs) to the IPublisher on which this operation is being called. To delete the IDataWriter the operation DeleteDatawriter or DeleteContainedEntities must be used.
For an example see Space.FooDataWriter detailed description.
| topic | The topic for which the IDataWriter is created. |
| qos | The DataWriterQos for the new IDataWriter. In case these settings are not self consistent, no IDataWriter is created. |
| listener | The IDataWriterListener instance which will be attached to the new IDataWriter. It is permitted to use null as the value of the listener: this behaves as a IDataWriterListener whose operations perform no action. |
| mask | a bit mask in which each bit enables the invocation of the IDataWriterListener for a certain status. |
| ReturnCode DDS.IPublisher.DeleteContainedEntities | ( | ) |
This operation deletes all the IDataWriter objects that were created by means of one of the CreateDataWriter operations on the IPublisher.
This operation deletes all the IDataWriter objects that were created by means of one of the CreateDatawriter operations on the IPublisher. In other words, it deletes all contained IDataWriter objects.
| ReturnCode DDS.IPublisher.DeleteDataWriter | ( | IDataWriter | dataWriter | ) |
This operation deletes a IDataWriter that belongs to the IPublisher.
This operation deletes a IDataWriter that belongs to the IPublisher. When the operation is called on a different IPublisher, as used when the IDataWriter was created, the operation has no effect and returns PreconditionNotMet. The deletion of the IDataWriter will automatically unregister all instances. Depending on the settings of WriterDataLifecycleQosPolicy, the deletion of the IDataWriter may also dispose of all instances.
| dataWriter | The IDataWriter which is to be deleted. |
| ReturnCode DDS.IPublisher.EndCoherentChanges | ( | ) |
This operation terminates the ‘coherent set’ initiated by the matching call to IPublisher.BeginCoherentChanges.
If there is no matching call to IPublisher.BeginCoherentChanges, the operation will return the error DDS.ReturnCode PreconditionNotMe.
| ReturnCode DDS.IPublisher.GetDefaultDataWriterQos | ( | ref DataWriterQos | qos | ) |
This operation gets the default DataWriterQos of the IPublisher.
The application must provide the DataWriterQos struct in which the QosPolicy settings can be stored and pass the qos reference to the operation. The operation writes the default DataWriterQos 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 SetDefaultDatawriterQos, or, if the call was never made, the default values as specified for each QosPolicy setting.
| qos | A reference to the DataWriterQos struct (provided by the application) in which the default DataWriterQos for the IDataWriter is written. |
| IDomainParticipant DDS.IPublisher.GetParticipant | ( | ) |
This operation returns the IDomainParticipant associated with the IPublisher.
Note that there is exactly one IDomainParticipant associated with each IPublisher. When the IPublisher was already deleted (there is no associated IDomainParticipant any more), the null reference is returned.
| ReturnCode DDS.IPublisher.GetQos | ( | ref PublisherQos | qos | ) |
This operation allows access to the existing set of QoS policies for a IPublisher.
This operation allows access to the existing set of QoS policies of a IPublisher on which this operation is used. This PublisherQos is stored at the location pointed to by the qos parameter.
| qos | A reference to the destination PublisherQos struct in which the QosPolicy settings will be copied. |
| IDataWriter DDS.IPublisher.LookupDataWriter | ( | string | topicName | ) |
This operation returns a previously created IDataWriter belonging to the IPublisher which is attached to a ITopic with the matching topicName.
This operation returns a previously created IDataWriter belonging to the IPublisher which is attached to a ITopic with the matching topicName. When multiple IDataWriter objects (which satisfy the same condition) exist, this operation will return one of them. It is not specified which one.
| topicName | the name of the ITopic, which is attached to the IDataWriter to look for. |
| ReturnCode DDS.IPublisher.ResumePublications | ( | ) |
This operation resumes a previously suspended publication.
If the IPublisher is suspended, this operation will resume the publication of all IDataWriter objects contained by this IPublisher. All data held in the history buffer of the IDataWriter's is actively published to the consumers. When the operation returns all IDataWriter's have resumed the publication of suspended updates.
| ReturnCode DDS.IPublisher.SetDefaultDataWriterQos | ( | DataWriterQos | qos | ) |
This operation sets the default DataWriterQos of the IPublisher.
The default DataWriterQos is used when one of the IPublisher.CreateDataWriter operations is used to create the IDataWriter which does not have the DataWriterQos as parameter.
The SetDefaultDataWriterQos operation checks if the DataWriterQos is self consistent. If it is not, the operation has no effect and returns InconsistentPolicy. The values set by this operation are returned by GetDefaultDataWriterQos.
| qos | The DataWriterQos struct, which contains the new default DataWriterQos for the newly created DataWriters. |
| ReturnCode DDS.IPublisher.SetListener | ( | IPublisherListener | listener, |
| StatusKind | mask | ||
| ) |
This operation attaches a PublisherListener to the IPublisher.
This operation attaches a PublisherListener to the IPublisher. Only one PublisherListener can be attached to each IPublisher. If a PublisherListener was already attached, the operation will replace it with the new one. When listener is null, it represents a listener that is treated as a No-Operation for all statuses activated in the bit mask.
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 PublisherListener operation is invoked and the communication status is reset to fase, as the listener implicitly accesses the status which is passed as a parameter to that operation. The status is reset prior to calling the listener, so if the application calls the Get<status_name>Status from inside the listener it will see the status already reset. An exception to this rule is the null listener, which does not reset the communication statuses for which it is invoked. The following statuses are applicable to the PublisherListener:
Be aware that the DDS.StatusKind.PublicationMatchStatus is 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. In this case the operation will return DDS.ReturnCode Unsupported.
Status bits are declared as a constant and can be used by the application in an OR operation to create a tailored mask. The value 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 IDataWriterListener of a contained IDataWriter, the IDataWriterListener on that contained IDataWriter is invoked instead of the PublisherListener. This means that a status change on a contained IDataWriter only invokes the PublisherListener if the contained IDataWriter itself does not handle the trigger event generated by the status change.
In case a status is not activated in the mask of the PublisherListener, the DomainParticipantListener of the containing IDomainParticipant is invoked (if attached and activated for the status that occurred). This allows the application to set a default behaviour in the DomainParticipantListener of the containing IDomainParticipant and an IPublisher specific behaviour when needed. In case the DomainParticipantListener is also not attached or the communication status is not activated in its mask, the application is not notified of the change.
| listener | The PublisherListener instance which will be attached to the publisher. |
| mask | a bit mask in which each bit enables the invocation of the PublisherListener for a certain status. |
| ReturnCode DDS.IPublisher.SetQos | ( | PublisherQos | qos | ) |
This operation replaces the existing set of QosPolicy settings for a IPublisher.
This operation replaces the existing set of QosPolicy settings for a IPublisher. The parameter qos contains the QosPolicy settings which is checked for self-consistency and mutability. When the application tries to change a QosPolicy setting for an enabled IPublisher, which can only be set before the IPublisher is enabled, the operation will fail and a ImmutablePolicy is returned. In other words, the application must provide the currently set QosPolicy settings in case of the immutable QosPolicy settings. Only the mutable QosPolicy settings can be changed. When qos contains conflicting QosPolicy settings (not self-consistent), the operation will fail and a InconsistentPolicy is returned. 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). If one or more of the partitions in the QoS structure have insufficient access rights configured then the SetQos function will fail with a PreconditionNotMet error code.
| qos | The new set of QosPolicy settings for the IPublisher. |
| ReturnCode DDS.IPublisher.SuspendPublications | ( | ) |
This operation will suspend the dissemination of the publications by all contained IDataWriter objects.
This operation suspends the publication of all IDataWriter objects contained by this IPublisher. The data written, disposed or unregistered by a IDataWriter is stored in the history buffer of the IDataWriter and therefore, depending on its QoS settings, the following operations may block (see the operation descriptions for more information):
Subsequent calls to this operation have no effect. When the IPublisher is deleted before ResumePublications is called, all suspended updates are discarded.
| ReturnCode DDS.IPublisher.WaitForAcknowledgments | ( | Duration | maxWait | ) |
This operation blocks the calling thread until either all data written by all contained DataWriters is acknowledged by the local infrastructure, or until the duration specified by maxWait parameter elapses, whichever happens first.
This operation blocks the calling thread until either all data written by all contained DataWriters is acknowledged by the local infrastructure, or until the duration specified by maxWait parameter elapses, whichever happens first. Data is acknowledged by the local infrastructure when it does not need to be stored in its IDataWriter’s local history. When a locally-connected subscription (including the networking service) has no more resources to store incoming samples it will start to reject these samples, resulting in their source DataWriters to store them temporarily in their own local history to be retransmitted at a later moment in time. In such scenarios, the WaitForAcknowledgments operation will block until all contained DataWriters have retransmitted their entire history, which is therefore effectively empty, or until the maxWait timeout expires, whichever happens first. In the first case the operation will return Ok, in the latter it will return Timeout.
Be aware that in case the operation returns Ok, the data has only been acknowledged by the local infrastructure: it does not mean all remote subscriptions have already received the data. However, delivering the data to remote nodes is then the sole responsibility of the networking service: even when the publishing application would terminate, all data that has not yet been received may be considered ‘on-route’ and will therefore eventually arrive (unless the networking service itself will crash). In contrast, if an IDataWriter would still have data in its local history buffer when it terminates, this data is considered ‘lost’. This operation is intended to be used only if one or more of the contained DataWriters has its ReliabilityQosPolicyKind set to ReliableReliabilityQos Otherwise the operation will return immediately with Ok, since best-effort DataWriters will never store rejected samples in their local history: they will just drop them and continue business as usual.
| maxWait | the maximum duration to block for tacknowledgments, after which the application thread is unblocked. The special constant Duration.Infinte can be used when the maximum waiting time does not need to be bounded. |
|
get |
This property returns the PublisherListener currently attached to the IPublisher.
Only one listener can be attached to the IPublisher at any particular time. This property returns the listener that is currently attached to the IPublisher.
Definition at line 2813 of file DdsDcpsInterfaces.cs.
1.8.13