Index

Package: DDS.DataWriter

Description

package DDS.DataWriter is

Summary: <<interface>> Allows an application to set the value of the data to be published under a given DDS.Topic.

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:

  • The base-class operations DDS.DataWriter.set_qos, DDS.DataWriter.get_qos, DDS.DataWriter.set_listener, DDS.DataWriter.get_listener, DDS.Entity.enable, DDS.Entity.get_statuscondition and DDS.Entity.get_status_changes
  • DDS.DataWriter.get_liveliness_lost_status, DDS.DataWriter.get_offered_deadline_missed_status, DDS.DataWriter.get_offered_incompatible_qos_status, DDS.DataWriter.get_publication_matched_status, DDS.DataWriter.get_reliable_writer_cache_changed_status, DDS.DataWriter.get_reliable_reader_activity_changed_status DDS.DataWriter.get_service_request_accepted_status

    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

    • Types

    Ref (abstract) 

    type Ref is limited interface and DDS.Domain_Entity.Ref;

    Ref_Access 

    type Ref_Access is access all Ref'Class;

    Subprograms & Entries

    Set_Qos 

    procedure Set_Qos 
    (Self: not null access Ref;
    Qos: in DDS.DataWriterQos) is abstract;

    Summary: Sets the writer QoS.

    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

    @param 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

    Set_Qos_With_Profile 

    procedure  Set_Qos_With_Profile 
    (Self: not null access Ref;
    Library_Name: String;
    Profile_Name: String) is abstract;

    Set_Qos_With_Profile 

    procedure  Set_Qos_With_Profile 
    (Self: not null access Ref;
    Library_Name: Standard.String;
    Profile_Name: Standard.String) is abstract;

    Summary: <<ext>> Change the QoS of this writer using the input XML QoS profile.

    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

    Get_Qos 

    procedure Get_Qos 
    (Self: not null access Ref;
    Qos: in out DDS.DataWriterQos) is abstract;

    Summary: Gets the writer QoS.

    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

    Set_Listener 

    procedure Set_Listener 
    (Self: not null access Ref;
    A_Listener: in DDS.DataWriterListener.Ref_Access;
    Mask: in DDS.StatusMask) is abstract;

    Summary: Sets the writer listener.

    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

    Get_Listener 

    function Get_Listener 
    (Self: not null access Ref) return DDS.DataWriterListener.Ref_Access is abstract;

    Summary: Get the writer listener.

    self: <<in>> Cannot be NULL

    Returns: DDS.DataWriterListener of the DDS.DataWriter.


    See also: Entity_get_listener

    Get_Topic 

    function Get_Topic 
    (Self: not null access Ref) return DDS.Topic.Ref_Access is abstract;

    Summary: This operation returns the DDS.Topic associated with the DDS.DataWriter.

    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.

    Get_Publisher 

    function Get_Publisher 
    (Self: not null access Ref) return access DDS.Publisher.Ref'Class is abstract;

    Summary: This operation returns the DDS.Publisher to which the DDS.DataWriter belongs.

    self: <<in>> Cannot be NULL

    Returns: DDS.Publisher to which the DDS.DataWriter belongs.

    Wait_For_Acknowledgments 

    procedure Wait_For_Acknowledgments 
    (Self: not null access Ref;
    Max_Wait: in DDS.Duration_T) is abstract;

    Summary: Blocks the calling thread until all data written by reliable DDS.DataWriter entity is acknowledged, or until timeout expires.

    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 return value of 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 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

    Wait_For_Asynchronous_Publishing 

    procedure Wait_For_Asynchronous_Publishing 
    (Self: not null access Ref;
    Max_Wait: in DDS.Duration_T) is abstract;

    Summary: <<ext>> Blocks the calling thread until asynchronous sending is complete.

    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

    Get_Liveliness_Lost_Status 

    procedure Get_Liveliness_Lost_Status 
    (Self: not null access Ref;
    Status: in out DDS.LivelinessLostStatus) is abstract;

    Summary: Accesses the DDS.LIVELINESS_LOST_STATUS communication status.

    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

    Get_Offered_Deadline_Missed_Status 

    procedure Get_Offered_Deadline_Missed_Status 
    (Self: not null access Ref;
    Status: in out DDS.OfferedDeadlineMissedStatus) is abstract;

    Summary: Accesses the DDS.OFFERED_DEADLINE_MISSED_STATUS communication status.

    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

    Get_Offered_Incompatible_Qos_Status 

    procedure Get_Offered_Incompatible_Qos_Status 
    (Self: not null access Ref;
    Status: in out DDS.OfferedIncompatibleQosStatus) is abstract;

    Summary: Accesses the DDS.OFFERED_INCOMPATIBLE_QOS_STATUS communication status.

    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

    Get_Publication_Matched_Status 

    procedure Get_Publication_Matched_Status 
    (Self: not null access Ref;
    Status: in out DDS.PublicationMatchedStatus) is abstract;

    Summary: Accesses the DDS.PUBLICATION_MATCHED_STATUS communication status.

    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

    Assert_Liveliness 

    procedure Assert_Liveliness 
    (Self: not null access Ref) is abstract;

    Summary: This operation manually asserts the liveliness of this DDS.DataWriter.

    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

    Get_Matched_Subscriptions 

    function Get_Matched_Subscriptions 
    (Self: not null access Ref) return DDS.InstanceHandle_Seq.Sequence is abstract;

    Summary: Retrieve the list of subscriptions currently "associated" with this DDS.DataWriter.

    Matched subscriptions include all those in the same domain that have a matching DDS.Topic, compatible QoS and common partition that the DDS.DomainParticipant has not indicated should be "ignored" by means of the DDS.DomainParticipant.ignore_subscription operation.

    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.

    self: <<in>> Cannot be NULL

    subscription_handles: <<inout>>. 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 the matches and the system can not 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 can not resize it, or DDS.RETCODE_NOT_ENABLED

    Get_Matched_Subscription_Data 

    function Get_Matched_Subscription_Data 
    (Self: not null access Ref;
    Subscription_Handle: in DDS.InstanceHandle_T) return DDS.SubscriptionBuiltinTopicData is abstract;

    Summary: This operation retrieves the information on a subscription that is currently "associated" with the DDS.DataWriter.

    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.

    Note: This operation does not retrieve the following information in DDS.SubscriptionBuiltinTopicData:

  • DDS.SubscriptionBuiltinTopicData.type_code
  • DDS.SubscriptionBuiltinTopicData.property
  • DDS.SubscriptionBuiltinTopicData.content_filter_property

    The above 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. 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

    • Get_Matched_Subscription_Locators 

    function Get_Matched_Subscription_Locators 
    (Self: not null access Ref) return DDS.Locator_Seq.Sequence is abstract;

    Summary: <<ext>> Retrieve the list of locators for subscriptions currently "associated" with this DDS.DataWriter.

    Matched subscription locators include locators for all those subscriptions in the same domain that have a matching DDS.Topic, compatible QoS and common partition that the DDS.DomainParticipant has not indicated should be "ignored" by means of the DDS.DomainParticipant.ignore_subscription operation.

    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

    Get_Reliable_Reader_Activity_Changed_Status 

    procedure Get_Reliable_Reader_Activity_Changed_Status 
    (Self: not null access Ref;
    status: in out DDS.ReliableReaderActivityChangedStatus) is abstract;

    Summary: <<ext>> Get the reliable reader activity changed status for this writer.

    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

    Get_Reliable_Writer_Cache_Changed_Status 

    procedure Get_Reliable_Writer_Cache_Changed_Status 
    (Self: not null access Ref;
    status: in out DDS.ReliableWriterCacheChangedStatus) is abstract;

    Summary: <<ext>> Get the reliable cache status for this writer.

    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

    Get_DataWriter_Cache_Status 

    procedure Get_DataWriter_Cache_Status 
    (Self: not null access Ref;
    status: in out DDS.DataWriterCacheStatus) is abstract;

    Summary: <<ext>> Get the datawriter cache status for this writer.

    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.

    Get_DataWriter_Protocol_Status 

    procedure Get_DataWriter_Protocol_Status 
    (Self: not null access Ref;
    status: in out DDS.DataWriterProtocolStatus) is abstract;

    Summary: <<ext>> Get the datawriter protocol status for this writer.

    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.

    Get_Matched_Subscription_Datawriter_Protocol_Status 

    procedure Get_Matched_Subscription_Datawriter_Protocol_Status 
    (Self: not null access Ref;
    status: in out DDS.DataWriterProtocolStatus;
    subscription_handle: DDS.InstanceHandle_T) is abstract;

    Summary: <<ext>> Get the datawriter protocol status for this writer, per matched subscription identified by the subscription_handle.

    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.

    Get_Matched_Subscription_Datawriter_Protocol_Status_By_Locator 

    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;

    Summary: <<ext>> Get the datawriter protocol status for this writer, per matched subscription identified by the locator.

    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.

    Flush 

    procedure Flush 
    (Self: not null access Ref) is abstract;

    Summary: <<ext>> Flushes the batch in progress in the context of the calling thread.

    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.

    WriteI 

    procedure WriteI 
    (Self: not null access Ref;
    Instance_Data: in System.Address;
    Handle: in DDS.InstanceHandle_T_Access) is abstract;