type Ref is limited interface and DDS.Domain_Entity.Ref;
type Ref_Access is access all Ref'Class;
procedure Set_Qos
( | Self | : not null access Ref; |
Qos | : in DDS.DataWriterQos) is abstract; |
This operation modifies the QoS of the DDS.DataWriter.
The DDS.DataWriterQos.user_data, DDS.DataWriterQos.deadline, DDS.DataWriterQos.latency_budget, DDS.DataWriterQos.ownership_strength, DDS.DataWriterQos.transport_priority, DDS.DataWriterQos.lifespan and DDS.DataWriterQos.writer_data_lifecycle can be changed. The other policies are immutable.
self: <<in>> Cannot be NULL
@condparam{CPP2_LANGUAGE_ONLY, the_qos, qos, <<in>> The DDS.DataWriterQos to be set to. Policies must be consistent. Immutable policies cannot be changed after DDS.DataWriter is enabled. The special value DDS.DATAWRITER_QOS_DEFAULT can be used to indicate that the QoS of the DDS.DataWriter should be changed to match the current default DDS.DataWriterQos set in the DDS.Publisher. Cannot be NULL.}
Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_IMMUTABLE_POLICY or DDS.RETCODE_INCONSISTENT_POLICY
See also: DDS.DataWriterQos for rules on consistency among QoS
See also: Entity_set_qos
See also: SharedEACallbackRules
procedure Set_Qos_With_Profile
( | Self | : not null access Ref; |
Library_Name | : String; | |
Profile_Name | : String) is abstract; |
procedure Set_Qos_With_Profile
( | Self | : not null access Ref; |
Library_Name | : Standard.String; | |
Profile_Name | : Standard.String) is abstract; |
This operation modifies the QoS of the DDS.DataWriter.
The DDS.DataWriterQos.user_data, DDS.DataWriterQos.deadline, DDS.DataWriterQos.latency_budget, DDS.DataWriterQos.ownership_strength, DDS.DataWriterQos.transport_priority, DDS.DataWriterQos.lifespan and DDS.DataWriterQos.writer_data_lifecycle can be changed. The other policies are immutable.
self: <<in>> Cannot be NULL
library_name: <<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDS.Publisher.set_default_library).
profile_name: <<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDS.Publisher.set_default_profile).
Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_IMMUTABLE_POLICY or DDS.RETCODE_INCONSISTENT_POLICY
See also: DDS.DataWriterQos for rules on consistency among QoS
See also: SharedEACallbackRules
procedure Get_Qos
( | Self | : not null access Ref; |
Qos | : in out DDS.DataWriterQos) is abstract; |
This procedure may potentially allocate memory depending on the sequences contained in some QoS policies.
self: <<in>> Cannot be NULL
qos: <<inout>> The DDS.DataWriterQos to be filled up. Cannot be NULL.
Raises: One of the DDSReturnTypesModules_std_retcodes
See also: Entity_get_qos
procedure Set_Listener
( | Self | : not null access Ref; |
A_Listener | : in DDS.DataWriterListener.Ref_Access; | |
Mask | : in DDS.StatusMask) is abstract; |
self: <<in>> Cannot be NULL
l: <<in>> DDS.DataWriterListener to set to
mask: <<in>> DDS.StatusMask associated with the DDS.DataWriterListener.
Raises: One of the DDSReturnTypesModules_std_retcodes
See also: Entity_set_listener
function Get_Listener
( | Self | : not null access Ref) return DDS.DataWriterListener.Ref_Access is abstract; |
self: <<in>> Cannot be NULL
Returns: DDS.DataWriterListener of the DDS.DataWriter.
See also: Entity_get_listener
function Get_Topic
( | Self | : not null access Ref) return DDS.Topic.Ref_Access is abstract; |
This is the same DDS.Topic that was used to create the DDS.DataWriter.
self: <<in>> Cannot be NULL
Returns: DDS.Topic that was used to create the DDS.DataWriter.
function Get_Publisher
( | Self | : not null access Ref) return access DDS.Publisher.Ref'Class is abstract; |
self: <<in>> Cannot be NULL
Returns: DDS.Publisher to which the DDS.DataWriter belongs.
procedure Wait_For_Acknowledgments
( | Self | : not null access Ref; |
Max_Wait | : in DDS.Duration_T) is abstract; |
This operation blocks the calling thread until either all data written by the reliable DDS.DataWriter entity is acknowledged by (a) all reliable DDS.DataReader entities that are matched and alive and (b) by all required subscriptions, or until the duration specified by the max_wait parameter elapses, whichever happens first. A successful completion indicates that all the samples written have been acknowledged by all reliable matched data readers and by all required subscriptions; a timeout indicates that max_wait elapsed before all the data was acknowledged.
Note that if a thread is blocked in the call to wait_for_acknowledgments on a DataWriter and a different thread writes new samples on the same DataWriter, the new samples must be acknowledged before unblocking the thread waiting on wait_for_acknowledgments.
If the DDS.DataWriter does not have DDS.ReliabilityQosPolicy kind set to RELIABLE, this operation will succeed immediately.
self: <<in>> Cannot be NULL
max_wait: <<in>> Specifies maximum time to wait for acknowledgements DDS.Duration_t .
Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_NOT_ENABLED, DDS.RETCODE_TIMEOUT
procedure Wait_For_Asynchronous_Publishing
( | Self | : not null access Ref; |
Max_Wait | : in DDS.Duration_T) is abstract; |
This operation blocks the calling thread (up to max_wait) until all data written by the asynchronous DDS.DataWriter is sent and acknowledged (if reliable) by all matched DDS.DataReader entities. A successful completion indicates that all the samples written have been sent and acknowledged where applicable; a time out indicates that max_wait elapsed before all the data was sent and/or acknowledged.
In other words, this guarantees that sending to best effort DDS.DataReader is complete in addition to what DDS.DataWriter.wait_for_acknowledgments provides.
If the DDS.DataWriter does not have DDS.PublishModeQosPolicy kind set to DDS.ASYNCHRONOUS_PUBLISH_MODE_QOS the operation will complete immediately with DDS.RETCODE_OK.
self: <<in>> Cannot be NULL
max_wait: <<in>> Specifies maximum time to wait for acknowledgements DDS.Duration_t .
Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_NOT_ENABLED, DDS.RETCODE_TIMEOUT
procedure Get_Liveliness_Lost_Status
( | Self | : not null access Ref; |
Status | : in out DDS.LivelinessLostStatus) is abstract; |
This also resets the status so that it is no longer considered changed.
self: <<in>> Cannot be NULL
status: <<inout>> DDS.LivelinessLostStatus to be filled in. Cannot be NULL.
Raises: One of the DDSReturnTypesModules_std_retcodes
procedure Get_Offered_Deadline_Missed_Status
( | Self | : not null access Ref; |
Status | : in out DDS.OfferedDeadlineMissedStatus) is abstract; |
This also resets the status so that it is no longer considered changed.
self: <<in>> Cannot be NULL
status: <<inout>> DDS.OfferedDeadlineMissedStatus to be filled in. Cannot be NULL.
Raises: One of the DDSReturnTypesModules_std_retcodes
procedure Get_Offered_Incompatible_Qos_Status
( | Self | : not null access Ref; |
Status | : in out DDS.OfferedIncompatibleQosStatus) is abstract; |
This also resets the status so that it is no longer considered changed.
self: <<in>> Cannot be NULL
status: <<inout>> DDS.OfferedIncompatibleQosStatus to be filled in. Cannot be NULL.
Raises: One of the DDSReturnTypesModules_std_retcodes
procedure Get_Publication_Matched_Status
( | Self | : not null access Ref; |
Status | : in out DDS.PublicationMatchedStatus) is abstract; |
This also resets the status so that it is no longer considered changed.
self: <<in>> Cannot be NULL
status: <<inout>> DDS.PublicationMatchedStatus to be filled in. Cannot be NULL.
Raises: One of the DDSReturnTypesModules_std_retcodes
procedure Assert_Liveliness
( | Self | : not null access Ref) is abstract; |
This is used in combination with the DDSLivelinessQosModule policy to indicate to RTI Connext that the DDS.DataWriter remains active.
You only need to use this operation if the DDSLivelinessQosModule setting is either DDS.MANUAL_BY_PARTICIPANT_LIVELINESS_QOS or DDS.MANUAL_BY_TOPIC_LIVELINESS_QOS. Otherwise, it has no effect.
Note: writing data via the FooDataWriter.write or FooDataWriter.write_w_timestamp operation asserts liveliness on the DDS.DataWriter itself, and its DDS.DomainParticipant. Consequently the use of assert_liveliness() is only needed if the application is not writing data regularly.
self: <<in>> Cannot be NULL
Raises: One of the DDSReturnTypesModules_std_retcodes or DDS.RETCODE_NOT_ENABLED
See also: DDS.LivelinessQosPolicy
function Get_Matched_Subscriptions
( | Self | : not null access Ref) return DDS.InstanceHandle_Seq.Sequence is abstract; |
A subscription is considered to be matching if all of the following criteria are true:
The handles returned in the subscription_handles list are the ones that RTI Connext uses to locally identify the corresponding matched DDS.DataReader entities. These handles match the ones that appear in the DDS.SampleInfo.instance_handle field of the DDS.SampleInfo when reading the DDS.SUBSCRIPTION_TOPIC_NAME builtin topic.
This API may return the subscription handles of subscriptions that are inactive. DDS.DataWriter.is_matched_subscription_active can be used to check this.
self: <<in>> Cannot be NULL
subscription_handles: <<inout>>. The handles of all the matched subscriptions.
The sequence will be grown if the sequence has ownership and the system has the corresponding resources. Use a sequence without ownership to avoid dynamic memory allocation. If the sequence is too small to store all of the matches and the system cannot resize the sequence, this procedure will fail with DDS.RETCODE_OUT_OF_RESOURCES.
The maximum number of matches possible is configured with DDS.DomainParticipantResourceLimitsQosPolicy. You can use a zero-maximum sequence without ownership to quickly check whether there are any matches without allocating any memory. Cannot be NULL..
Raises: One of the DDSReturnTypesModules_std_retcodes, or DDS.RETCODE_OUT_OF_RESOURCES if the sequence is too small and the system cannot resize it, or DDS.RETCODE_NOT_ENABLED
function Get_Matched_Subscription_Data
( | Self | : not null access Ref; |
Subscription_Handle | : in DDS.InstanceHandle_T) return DDS.SubscriptionBuiltinTopicData is abstract; |
The subscription_handle must correspond to a subscription currently associated with the DDS.DataWriter. Otherwise, the operation will fail and fail with DDS.RETCODE_BAD_PARAMETER. Use DDS.DataWriter.get_matched_subscriptions to find the subscriptions that are currently matched with the DDS.DataWriter.
The above information is also available through DDS.DataReaderListener::on_data_available() (if a reader listener is installed on the DDS.SubscriptionBuiltinTopicDataDataReader).
When the subscription data is updated, for example when the content filter property changes, there is a small window of time in between when the DataWriter is made aware of these changes and when they actually take effect. Taking effect in this example means that the DataWriter will perform writer-side filtering using the new filter property values (filter expression and/or parameters).
When the DataWriter is made aware of the changes they will first be seen in the DDS.DataReaderListener::on_data_available() of the DDS.SubscriptionBuiltinTopicDataDataReader. When these changes are applied, they will be seen in the output of this API because this API blocks until the most recent changes known to the DataWriter have taken effect. This API will only block when called outside of a listener callback, in order to not block the internal threads from making progress.
If application behavior depends on being made aware of information about a subscription only after it has taken effect on the DataWriter, the recommended pattern for usage of this API is to wait for subscription data to be received either through polling this API or by installing a listener on the DDS.SubscriptionBuiltinTopicDataDataReader. When a new sample is received by the builtin DataReader, this API may be called in a separate thread and will return the expected matched subscription data once it has been applied to the DataWriter.
Because this API blocks, it is possible for this API to time out while waiting for the changes to be applied. A timeout may happen if the DataReader's subscription data is changing rapidly, preventing the DataWriter from returning valid information before newer data has been received, or if an application is performing a task in a listener callback, thereby preventing the middleware's threads from executing events in a timely manner.
Note: This operation does not retrieve the DDS.SubscriptionBuiltinTopicData.type_code. This information is available through DDS.DataReaderListener::on_data_available() (if a reader listener is installed on the DDS.SubscriptionBuiltinTopicDataDataReader).
self: <<in>> Cannot be NULL
subscription_data: <<inout>>. The information to be filled in on the associated subscription. Cannot be NULL.
subscription_handle: <<in>>. Handle to a specific subscription associated with the DDS.DataReader. Must correspond to a subscription currently associated with the DDS.DataWriter. Cannot be NULL.
Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_NOT_ENABLED, or DDS.RETCODE_TIMEOUT
function Get_Matched_Subscription_Locators
( | Self | : not null access Ref) return DDS.Locator_Seq.Sequence is abstract; |
The locators returned in the locators list are the ones that are used by the DDS implementation to communicate with the corresponding matched DDS.DataReader entities.
self: <<in>> Cannot be NULL
locators: <<inout>>. Handles of all the matched subscription locators.
The sequence will be grown if the sequence has ownership and the system has the corresponding resources. Use a sequence without ownership to avoid dynamic memory allocation. If the sequence is too small to store all the matches and the system can not resize the sequence, this procedure will fail with DDS.RETCODE_OUT_OF_RESOURCES. Cannot be NULL..
Raises: One of the DDSReturnTypesModules_std_retcodes, or DDS.RETCODE_OUT_OF_RESOURCES if the sequence is too small and the system can not resize it, or DDS.RETCODE_NOT_ENABLED
procedure Get_Reliable_Reader_Activity_Changed_Status
( | Self | : not null access Ref; |
status | : in out DDS.ReliableReaderActivityChangedStatus) is abstract; |
procedure set_Reliable_Reader_Activity_Changed_Status
( | Self | : not null access Ref; |
status | : in DDS.ReliableReaderActivityChangedStatus) is abstract; |
This also resets the status so that it is no longer considered changed.
self: <<in>> Cannot be NULL
status: <<inout>> DDS.ReliableReaderActivityChangedStatus to be filled in. Cannot be NULL.
Raises: One of the DDSReturnTypesModules_std_retcodes
procedure Get_Reliable_Writer_Cache_Changed_Status
( | Self | : not null access Ref; |
status | : in out DDS.ReliableWriterCacheChangedStatus) is abstract; |
This also resets the status so that it is no longer considered changed.
self: <<in>> Cannot be NULL
status: <<inout>> DDS.ReliableWriterCacheChangedStatus to be filled in. Cannot be NULL.
Raises: One of the DDSReturnTypesModules_std_retcodes
procedure Get_DataWriter_Cache_Status
( | Self | : not null access Ref; |
status | : in out DDS.DataWriterCacheStatus) is abstract; |
This also resets the status so that it is no longer considered changed.
self: <<in>> Cannot be NULL
status: <<inout>> DDS.DataWriterCacheStatus to be filled in. Cannot be NULL.
Raises: One of the DDSReturnTypesModules_std_retcodes or DDS.RETCODE_NOT_ENABLED.
procedure Get_DataWriter_Protocol_Status
( | Self | : not null access Ref; |
status | : in out DDS.DataWriterProtocolStatus) is abstract; |
This also resets the status so that it is no longer considered changed.
self: <<in>> Cannot be NULL
status: <<inout>> DDS.DataWriterProtocolStatus to be filled in. Cannot be NULL.
Raises: One of the DDSReturnTypesModules_std_retcodes or DDS.RETCODE_NOT_ENABLED.
procedure Get_Matched_Subscription_Datawriter_Protocol_Status
( | Self | : not null access Ref; |
status | : in out DDS.DataWriterProtocolStatus; | |
subscription_handle | : DDS.InstanceHandle_T) is abstract; |
This also resets the status so that it is no longer considered changed.
Note: Status for a remote entity is only kept while the entity is alive. Once a remote entity is no longer alive, its status is deleted.
self: <<in>> Cannot be NULL
status: <<inout>> DDS.DataWriterProtocolStatus to be filled in. Cannot be NULL.
subscription_handle: <<in>> Handle to a specific subscription associated with the DDS.DataReader. Cannot be NULL. Must correspond to a subscription currently associated with the DDS.DataWriter.
Raises: One of the DDSReturnTypesModules_std_retcodes or DDS.RETCODE_NOT_ENABLED.
procedure Get_Matched_Subscription_Datawriter_Protocol_Status_By_Locator
( | Self | : not null access Ref; |
status | : in out DDS.DataWriterProtocolStatus; | |
locator | : DDS.Locator_T) is abstract; |
This also resets the status so that it is no longer considered changed.
Note: Status for a remote entity is only kept while the entity is alive. Once a remote entity is no longer alive, its status is deleted.
self: <<in>> Cannot be NULL
status: <<inout>> DDS.DataWriterProtocolStatus to be filled in Cannot be NULL.
locator: <<in>> Locator to a specific locator associated with the DDS.DataReader. Cannot be NULL. Must correspond to a locator of one or more subscriptions currently associated with the DDS.DataWriter. Raises: One of the DDSReturnTypesModules_std_retcodes or DDS.RETCODE_NOT_ENABLED.
procedure Flush
( | Self | : not null access Ref) is abstract; |
After being flushed, the batch is available to be sent on the network.
If the DDS.DataWriter does not have DDS.PublishModeQosPolicy kind set to DDS.ASYNCHRONOUS_PUBLISH_MODE_QOS, the batch will be sent on the network immediately (in the context of the calling thread).
If the DDS.DataWriter does have DDS.PublishModeQosPolicy kind set to DDS.ASYNCHRONOUS_PUBLISH_MODE_QOS, the batch will be sent in the context of the asynchronous publishing thread.
This operation may block in the same conditions as FooDataWriter.write.
If this operation does block, the RELIABILITY max_blocking_time configures the maximum time the write operation may block (waiting for space to become available). If max_blocking_time elapses before the DDS_DataWriter is able to store the modification without exceeding the limits, the operation will fail with DDS_RETCODE_TIMEOUT.
MT Safety:
flush() is only thread-safe with batching if DDS.BatchQosPolicy.thread_safe_write is TRUE.
self: <<in>> Cannot be NULL
Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_TIMEOUT, DDS.RETCODE_OUT_OF_RESOURCES or DDS.RETCODE_NOT_ENABLED.
procedure WriteI
( | Self | : not null access Ref; |
Instance_Data | : in System.Address; | |
Handle | : in DDS.InstanceHandle_T_Access; | |
MetpImpl | : not null access DDS.MetpTypeSupport.Ref'Class) is abstract; |
procedure Get_LoanI
( | Self | : not null access Ref; |
Loan_Ret | : out System.Address; | |
Initialize_Data | : out Standard.Boolean; | |
MetpImpl | : not null access DDS.MetpTypeSupport.Ref'Class) is abstract; |
procedure Discard_LoanI
( | Self | : not null access Ref; |
Sample | : System.Address; | |
MetpImpl | : not null access DDS.MetpTypeSupport.Ref'Class) is abstract; |
procedure call_listener
( | Self | : not null access Ref; |
mask | : StatusMask) is abstract; |
procedure set_reliable_writer_cache_changed_status
( | Self | : not null access Ref; |
To | : ReliableWriterCacheChangedStatus) is abstract; |
procedure set_datawriter_cache_status
( | Self | : not null access Ref; |
To | : DataWriterCacheStatus) is abstract; |
procedure set_datawriter_protocol_status
( | Self | : not null access Ref; |
To | : DataWriterProtocolStatus) is abstract; |
procedure set_matched_subscription_datawriter_protocol_status
( | Self | : not null access Ref; |
To | : DDS.DataWriterProtocolStatus; | |
handle | : DDS.InstanceHandle_T) is abstract; |
procedure set_matched_subscription_datawriter_protocol_status_by_locator
( | Self | : not null access Ref; |
status | : DDS.DataWriterProtocolStatus; | |
locator | : DDS.Locator_T) is abstract; |
QoS:
DDS.DataWriterQos
Status:
DDS.LIVELINESS_LOST_STATUS, DDS.LivelinessLostStatus;
DDS.OFFERED_DEADLINE_MISSED_STATUS, DDS.OfferedDeadlineMissedStatus;
DDS.OFFERED_INCOMPATIBLE_QOS_STATUS, DDS.OfferedIncompatibleQosStatus;
DDS.PUBLICATION_MATCHED_STATUS, DDS.PublicationMatchedStatus;
DDS.RELIABLE_READER_ACTIVITY_CHANGED_STATUS, DDS.ReliableReaderActivityChangedStatus;
DDS.RELIABLE_WRITER_CACHE_CHANGED_STATUS, DDS.ReliableWriterCacheChangedStatus.
Listener:
DDS.DataWriterListener
A DDS.DataWriter is attached to exactly one DDS.Publisher, that acts as a factory for it.
A DDS.DataWriter is bound to exactly one DDS.Topic and therefore to exactly one data type. The DDS.Topic must exist prior to the DDS.DataWriter's creation.
DDS.DataWriter is an abstract class. It must be specialized for each particular application data-type (see DDSUserDataQosModule). The additional methods or functions that must be defined in the auto-generated class for a hypothetical application type Foo are specified in the example type DDS.DataWriter.
The following operations may be called even if the DDS.DataWriter is not enabled. Other operations will fail with DDS.RETCODE_NOT_ENABLED if called on a disabled DDS.DataWriter:
Several DDS.DataWriter may operate in different threads. If they share the same DDS.Publisher, the middleware guarantees that its operations are thread-safe.
See also: FooDataWriter
See also: SharedEACallbackRules