Index

Package: DDS.Publisher

Description

package DDS.Publisher is

Summary: <<interface>> A publisher is the object responsible for the actual dissemination of publications.

QoS:
DDS.PublisherQos

Listener:
DDS.PublisherListener

A publisher acts on the behalf of one or several DDS.DataWriter objects that belong to it. When it is informed of a change to the data associated with one of its DDS.DataWriter objects, it decides when it is appropriate to actually send the data-update message. In making this decision, it considers any extra information that goes with the data (timestamp, writer, etc.) as well as the QoS of the DDS.Publisher and the DDS.DataWriter.

The following operations may be called even if the DDS.Publisher is not enabled. Other operations will fail with the value DDS.RETCODE_NOT_ENABLED if called on a disabled DDS.Publisher:

  • DDS.Entity.enable,
  • DDS.Publisher.set_qos, DDS.Publisher.get_qos , DDS.Publisher.set_qos_with_profile\endif
  • DDS.Publisher.set_listener, DDS.Publisher.get_listener,
  • DDS.Entity.get_statuscondition, DDS.Entity.get_status_changes
  • DDS.Publisher.create_datawriter, \ifnot CPP2_LANGUAGE_ONLY DDS.Publisher.create_datawriter_with_profile, DDS.Publisher.delete_contained_entities, DDS.Publisher.delete_datawriter,
  • DDS.Publisher.set_default_datawriter_qos, DDS.Publisher.set_default_datawriter_qos_with_profile, DDS.Publisher.get_default_datawriter_qos, DDS.Publisher.wait_for_acknowledgments, DDS.Publisher.set_default_library, DDS.Publisher.set_default_profile,


    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;

    Ref_Access_Access 

    type Ref_Access_Access is access all Ref_Access;

    Ref_Access_Array 

    type Ref_Access_Array is array (Natural range <>) of aliased Ref_Access;

    Constants & Global variables

    DATAWRITER_QOS_DEFAULT 

    DATAWRITER_QOS_DEFAULT : aliased  constant DataWriterQos with
     Convention => Ada,
     Import,
     Link_Name => "DDS__Publisher_DATAWRITER_QOS_DEFAULT";

    Summary: Special value for creating data reader with default QoS.

    When used in DDS.Subscriber.create_datareader, this special value is used to indicate that the DDS.DataReader should be created with the default DDS.DataReader QoS by means of the operation get_default_datareader_qos and using the resulting QoS to create the DDS.DataReader.

    When used in DDS.Subscriber.set_default_datareader_qos, this special value is used to indicate that the default QoS should be reset back to the initial value that would be used if the DDS.Subscriber.set_default_datareader_qos operation had never been called.

    When used in DDS.DataReader.set_qos, this special value is used to indicate that the QoS of the DDS.DataReader should be changed to match the current default QoS set in the DDS.Subscriber that the DDS.DataReader belongs to.

    Note: You cannot use this value to get the default QoS values for a DataReader; for this purpose, use DDS.DomainParticipant.get_default_datareader_qos.


    See also: DDS.Subscriber.create_datareader
    See also: DDS.Subscriber.set_default_datareader_qos
    See also: DDS.DataReader.set_qos

    DATAWRITER_QOS_USE_TOPIC_QOS 

    DATAWRITER_QOS_USE_TOPIC_QOS :  aliased  constant DataWriterQos with
     Convention => Ada,
     Import,
     Link_Name => "DDS__Publisher_DATAWRITER_QOS_USE_TOPIC_QOS";

    Summary: Special value for creating DDS.DataReader with a combination of the default DDS.DataReaderQos and the DDS.TopicQos.

    The use of this value is equivalent to the application obtaining the default DDS.DataReaderQos and the DDS.TopicQos (by means of the operation DDS.Topic.get_qos) and then combining these two QoS using the operation DDS.Subscriber.copy_from_topic_qos whereby any policy that is set on the DDS.TopicQos "overrides" the corresponding policy on the default QoS. The resulting QoS is then applied to the creation of the DDS.DataReader.

    This value should only be used in DDS.Subscriber.create_datareader.


    See also: DDS.Subscriber.create_datareader
    See also: DDS.Subscriber.get_default_datareader_qos
    See also: DDS.Topic.get_qos
    See also: DDS.Subscriber.copy_from_topic_qos

    Subprograms & Entries

    Initialize 

    procedure Initialize 
    (Self: in out Ref_Access) is null;

    Finalize 

    procedure Finalize 
    (Self: in out Ref_Access) is null;

    Copy 

    procedure Copy 
    (Dst: in out Ref_Access;
    Src: in Ref_Access);

    Create_DataWriter (abstract) 

    function Create_DataWriter 
    (Self: not null access Ref;
    A_Topic: in DDS.Topic.Ref_Access;
    Qos: in DDS.DataWriterQos := DATAWRITER_QOS_DEFAULT;
    A_Listener: in DDS.DataWriterListener.Ref_Access := null;
    Mask: in DDS.StatusMask := STATUS_MASK_NONE) return DDS.DataWriter.Ref_Access is abstract;

    Summary: Creates a DDS.DataWriter that will be attached and belong to the DDS.Publisher.

    For each application-defined type, Foo, there is an implied, auto-generated class FooDataWriter that extends DDS.DataWriter and contains the operations to write data of type Foo.

    Note that a common application pattern to construct the QoS for the DDS.DataWriter is to:

  • Retrieve the QoS policies on the associated DDS.Topic by means of the DDS.Topic.get_qos operation.
  • Retrieve the default DDS.DataWriter qos by means of the DDS.Publisher.get_default_datawriter_qos operation.
  • Combine those two QoS policies (for example, using DDS.Publisher.copy_from_topic_qos) and selectively modify policies as desired.

    When a DDS.DataWriter is created, only those transports already registered are available to the DDS.DataWriter. See NDDS_TransportBuiltinsComponent for details on when a builtin transport is registered.

    Precondition: If publisher is enabled, topic must have been enabled. Otherwise, this operation will fail and no DDS.DataWriter will be created.

    Precondition: The given DDS.Topic must have been created from the same participant as this publisher. If it was created from a different participant, this procedure will fail.

    MT Safety:
    UNSAFE. If DDS.DATAWRITER_QOS_DEFAULT is used for the qos parameter, it is not safe to create the datawriter while another thread may be simultaneously calling DDS.Publisher.set_default_datawriter_qos.

    self: <<in>> Cannot be NULL

    topic: <<in>> The DDS.Topic that the DDS.DataWriter will be associated with. Cannot be NULL.

    qos: <<in>> QoS to be used for creating the new DDS.DataWriter. The special value DDS.DATAWRITER_QOS_DEFAULT can be used to indicate that the DDS.DataWriter should be created with the default DDS.DataWriterQos set in the DDS.Publisher. The special value DDS.DATAWRITER_QOS_USE_TOPIC_QOS can be used to indicate that the DDS.DataWriter should be created with the combination of the default DDS.DataWriterQos set on the DDS.Publisher and the DDS.TopicQos of the DDS.Topic. Cannot be NULL.

    listener: <<in>> The listener of the DDS.DataWriter.

    mask: <<in>>. Changes of communication status to be invoked on the listener. See DDS.StatusMask.

    Returns: A DDS.DataWriter of a derived class specific to the data type associated with the DDS.Topic or NULL if an error occurred.


    See also: FooDataWriter
    See also: DDSQosTypesModule_usage for information on setting QoS before entity creation
    See also: DDS.DataWriterQos for rules on consistency among QoS
    See also: DDS.DATAWRITER_QOS_DEFAULT
    See also: DDS.DATAWRITER_QOS_USE_TOPIC_QOS
    See also: DDS.Publisher.create_datawriter_with_profile
    See also: DDS.Publisher.get_default_datawriter_qos
    See also: DDS.Topic.set_qos
    See also: DDS.Publisher.copy_from_topic_qos
    See also: DDS.DataWriter.set_listener

    • Create_DataWriter_With_Profile (abstract) 

    function Create_DataWriter_With_Profile 
    (Self: not null access Ref;
    A_Topic: in DDS.Topic.Ref_Access;
    Library_Name: in DDS.String;
    profile_name: in DDS.String;
    A_Listener: in DDS.DataWriterListener.Ref_Access := null;
    Mask: in DDS.StatusMask := STATUS_MASK_NONE) return DDS.DataWriter.Ref_Access is abstract;

    Create_DataWriter_With_Profile (abstract) 

    function Create_DataWriter_With_Profile 
    (Self: not null access Ref;
    A_Topic: in DDS.Topic.Ref_Access;
    Library_Name: in Standard.String;
    profile_name: in Standard.String;
    A_Listener: in DDS.DataWriterListener.Ref_Access := null;
    Mask: in DDS.StatusMask := STATUS_MASK_NONE) return DDS.DataWriter.Ref_Access is abstract;

    Summary: <<ext>> Creates a DDS.DataWriter object using the DDS.DataWriterQos associated with the input XML QoS profile.

    The DDS.DataWriter will be attached and belong to the DDS.Publisher.

    For each application-defined type, Foo, there is an implied, auto-generated class FooDataWriter that extends DDS.DataWriter and contains the operations to write data of type Foo.

    When a DDS.DataWriter is created, only those transports already registered are available to the DDS.DataWriter. See NDDS_TransportBuiltinsComponent for details on when a builtin transport is registered.

    Precondition: If publisher is enabled, topic must have been enabled. Otherwise, this operation will fail and no DDS.DataWriter will be created.

    Precondition: The given DDS.Topic must have been created from the same participant as this publisher. If it was created from a different participant, this procedure will return NULL.

    self: <<in>> Cannot be NULL

    topic: <<in>> The DDS.Topic that the DDS.DataWriter will be associated with. 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).

    listener: <<in>> The listener of the DDS.DataWriter.

    mask: <<in>>. Changes of communication status to be invoked on the listener. See DDS.StatusMask.

    Returns: A DDS.DataWriter of a derived class specific to the data type associated with the DDS.Topic or NULL if an error occurred.


    See also: FooDataWriter
    See also: DDSQosTypesModule_usage for information on setting QoS before entity creation
    See also: DDS.DataWriterQos for rules on consistency among QoS
    See also: DDS.Publisher.create_datawriter
    See also: DDS.Publisher.get_default_datawriter_qos
    See also: DDS.Topic.set_qos
    See also: DDS.Publisher.copy_from_topic_qos
    See also: DDS.DataWriter.set_listener

    Delete_DataWriter (abstract) 

    procedure Delete_DataWriter 
    (Self: not null access Ref;
    A_DataWriter: in out DDS.DataWriter.Ref_Access) is abstract;

    Summary: Deletes a DDS.DataWriter that belongs to the DDS.Publisher.

    The deletion of the DDS.DataWriter will automatically unregister all instances. Depending on the settings of the DDSWriterDataLifecycleQosModule QosPolicy, the deletion of the DDS.DataWriter may also dispose all instances.

    \ifnot BROKEN_SECTIONS

    Special Instructions if Using 'Timestamp' APIs and BY_SOURCE_TIMESTAMP Destination Ordering:

    \endif

    If the DataWriter's DDS.DestinationOrderQosPolicy.kind is DDS.BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS, deleting the DataWriter may fail if your application has previously used the operations that receive a timestamp (FooDataWriter.write_w_timestamp, FooDataWriter.register_instance_w_timestamp, FooDataWriter.unregister_instance_w_timestamp, or FooDataWriter.dispose_w_timestamp) with a timestamp larger (later) than the time at which the writer is deleted. To prevent the deletion from failing in this situation, either:

  • Change the DDSWriterDataLifecycleQosModule QoS policy so that RTI Connext will not autodispose unregistered instances (set DDS.WriterDataLifecycleQosPolicy.autodispose_unregistered_instances to DDS.BOOLEAN_FALSE) or
  • Explicitly call FooDataWriter.unregister_instance_w_timestamp for all instances modified with the previous timestamp-based functions before deleting the DataWriter.

    Precondition: If the DDS.DataWriter does not belong to the DDS.Publisher, the operation will fail with DDS.RETCODE_PRECONDITION_NOT_MET.

    Postcondition: Listener installed on the DDS.DataWriter will not be called after this procedure completes successfully.

    @mtsafety_delete

    self: <<in>> Cannot be NULL

    a_datawriter: <<in>> The DDS.DataWriter to be deleted. Raises: One of the DDSReturnTypesModules_std_retcodes or DDS.RETCODE_PRECONDITION_NOT_MET.

    • Lookup_DataWriter (abstract) 

    function Lookup_DataWriter 
    (Self: not null access Ref;
    Topic_Name: in DDS.String_Ptr) return DDS.DataWriter.Ref_Access is abstract;

    Summary: Retrieves the DDS.DataWriter for a specific DDS.Topic.

    This returned DDS.DataWriter is either enabled or disabled.

    If more than one DDS.DataWriter is attached to the DDS.Publisher with the same topic_name, then this operation may return any one of them.

    MT Safety:
    UNSAFE. It is not safe to lookup a DDS.DataWriter in one thread while another thread is simultaneously creating or destroying that DDS.DataWriter.

    self: <<in>> Cannot be NULL

    topic_name: <<in>> Name of the DDS.Topic associated with the DDS.DataWriter that is to be looked up. Cannot be NULL.

    Returns: A DDS.DataWriter that belongs to the DDS.Publisher attached to the DDS.Topic with topic_name. If no such DDS.DataWriter exists, this operation returns NULL.

    This returned DDS.DataWriter is either enabled or disabled.

    If more than one DDS.DataWriter is attached to the DDS.Publisher with the same topic_name, then this operation may return any one of them.

    MT Safety:
    UNSAFE. It is not safe to lookup a DDS.DataWriter in one thread while another thread is simultaneously creating or destroying that DDS.DataWriter.

    Delete_Contained_Entities (abstract) 

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

    Summary: Deletes all the entities that were created by means of the "create" operation on the DDS.Publisher.

    Deletes all contained DDS.DataWriter objects. Once DDS.Publisher.delete_contained_entities completes successfully, the application may delete the DDS.Publisher, knowing that it has no contained DDS.DataWriter objects.

    The operation will fail with DDS.RETCODE_PRECONDITION_NOT_MET if any of the contained entities is in a state where it cannot be deleted.

    @mtsafety_delete

    self: <<in>> Cannot be NULL

    Raises: One of the DDSReturnTypesModules_std_retcodes or DDS.RETCODE_PRECONDITION_NOT_MET.

    Set_Qos (abstract) 

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

    Summary: Sets the publisher QoS.

    This operation modifies the QoS of the DDS.Publisher.

    The DDS.PublisherQos.group_data, DDS.PublisherQos.partition and DDS.PublisherQos.entity_factory can be changed. The other policies are immutable.

    self: <<in>> Cannot be NULL

    @param qos <<in>> DDS.PublisherQos to be set to. Policies must be consistent. Immutable policies cannot be changed after DDS.Publisher is enabled. The special value DDS.PUBLISHER_QOS_DEFAULT can be used to indicate that the QoS of the DDS.Publisher should be changed to match the current default DDS.PublisherQos set in the DDS.DomainParticipant. Cannot be NULL.

    Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_IMMUTABLE_POLICY, or DDS.RETCODE_INCONSISTENT_POLICY.


    See also: DDS.PublisherQos for rules on consistency among QoS


    See also: Entity_set_qos


    See also: SharedEACallbackRules

    Set_Qos_With_Profile (abstract) 

    procedure Set_Qos_With_Profile 
    (Self: not null access Ref;
    library_name: in String;
    profile_name: in String) is abstract;

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

    This operation modifies the QoS of the DDS.Publisher.

    The DDS.PublisherQos.group_data, DDS.PublisherQos.partition and DDS.PublisherQos.entity_factory 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.PublisherQos for rules on consistency among QoS


    See also: SharedEACallbackRules

    Get_Qos (abstract) 

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

    Summary: Gets the publisher QoS.

    This procedure may potentially allocate memory depending on the sequences contained in some QoS policies.

    self: <<in>> Cannot be NULL

    qos: <<in>> DDS.PublisherQos to be filled in. Cannot be NULL.

    Raises: One of the DDSReturnTypesModules_std_retcodes


    See also: Entity_get_qos

    Set_Listener (abstract) 

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

    Summary: Sets the publisher listener.

    self: <<in>> Cannot be NULL

    l: <<in>> DDS.PublisherListener to set to.

    mask: <<in>> DDS.StatusMask associated with the DDS.PublisherListener.

    Raises: One of the DDSReturnTypesModules_std_retcodes


    See also: Entity_set_listener

    Get_Listener (abstract) 

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

    Summary: Get the publisher listener.

    self: <<in>> Cannot be NULL

    Returns: DDS.PublisherListener of the DDS.Publisher.


    See also: Entity_get_listener

    Suspend_Publications (abstract) 

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

    Summary: Indicates to RTI Connext that the application is about to make multiple modifications using DDS.DataWriter objects belonging to the DDS.Publisher.

    It is a hint to RTI Connext so it can optimize its performance by e.g., holding the dissemination of the modifications and then batching them.

    The use of this operation must be matched by a corresponding call to DDS.Publisher.resume_publications indicating that the set of modifications has completed.

    If the DDS.Publisher is deleted before DDS.Publisher.resume_publications is called, any suspended updates yet to be published will be discarded.

    RTI Connext is not required and does not currently make use of this hint in any way. However, similar results can be achieved by using asynchronous publishing. Combined with DDS.FlowController, DDS.ASYNCHRONOUS_PUBLISH_MODE_QOS DDS.DataWriter instances allow the user even finer control of traffic shaping and sample coalescing.

    self: <<in>> Cannot be NULL

    Raises: One of the DDSReturnTypesModules_std_retcodes or DDS.RETCODE_NOT_ENABLED.


    See also: DDS.FlowController
    See also: DDS.FlowController.trigger_flow
    See also: DDS.ON_DEMAND_FLOW_CONTROLLER_NAME
    See also: DDS.PublishModeQosPolicy

    Resume_Publications (abstract) 

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

    Summary: Indicates to RTI Connext that the application has completed the multiple changes initiated by the previous DDS.Publisher.suspend_publications.

    This is a hint to RTI Connext that can be used for example, to batch all the modifications made since the DDS.Publisher.suspend_publications.

    RTI Connext is not required and does not currently make use of this hint in any way. However, similar results can be achieved by using asynchronous publishing. Combined with DDS.FlowController, DDS.ASYNCHRONOUS_PUBLISH_MODE_QOS DDS.DataWriter instances allow the user even finer control of traffic shaping and sample coalescing.

    Precondition: A call to DDS.Publisher.resume_publications must match a previous call to DDS.Publisher.suspend_publications. Otherwise the operation will fail with DDS.RETCODE_PRECONDITION_NOT_MET.

    self: <<in>> Cannot be NULL

    Raises: One of the DDSReturnTypesModules_std_retcodes or DDS.RETCODE_PRECONDITION_NOT_MET or DDS.RETCODE_NOT_ENABLED.


    See also: DDS.FlowController
    See also: DDS.FlowController.trigger_flow
    See also: DDS.ON_DEMAND_FLOW_CONTROLLER_NAME
    See also: DDS.PublishModeQosPolicy

    Begin_Coherent_Changes (abstract) 

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

    Summary: Indicates that the application will begin a coherent set of modifications using DDS.DataWriter objects attached to the DDS.Publisher.

    A 'coherent set' is a set of modifications that must be propagated in such a way that they are interpreted at the receiver's 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 connectivity change may occur in the middle of a set of coherent changes; for example, the set of partitions used by the DDS.Publisher or one of its DDS.Subscriber s may change, a late-joining DDS.DataReader 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 DDS.Publisher.end_coherent_changes.

    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).

    Note: Coherent sets don't apply to Topic Queries. If a DDS.TopicQuery selects only a subset of samples that was published as a coherent set, the subscribing application will receive them regardless of their membership to the coherent set.

    self: <<in>> Cannot be NULL

    Raises: One of the DDSReturnTypesModules_std_retcodes or DDS.RETCODE_NOT_ENABLED.


    See also: DDS.PresentationQosPolicy

    End_Coherent_Changes (abstract) 

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

    Summary: Terminates the coherent set initiated by the matching call to DDS.Publisher.begin_coherent_changes.

    Precondition: If there is no matching call to DDS.Publisher.begin_coherent_changes the operation will fail with DDS.RETCODE_PRECONDITION_NOT_MET.

    self: <<in>> Cannot be NULL

    Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_PRECONDITION_NOT_MET or DDS.RETCODE_NOT_ENABLED.

    Wait_For_Acknowledgments (abstract) 

    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 the Publisher's reliable DataWriters is acknowledged, or until timeout expires.

    This operation blocks the calling thread until either all data written by the reliable DataWriters entities 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; 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 this operation on a DDS.Publisher and a different thread writes new samples on any of the reliable DataWriters that belong to this Publisher, the new samples must be acknowledged before unblocking the thread that is waiting on this operation.

    If none of the DDS.DataWriter instances have DDS.ReliabilityQosPolicy kind set to RELIABLE, the operation will complete successfully.

    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 (abstract) 

    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 entities 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; if it times out, this 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.Publisher.wait_for_acknowledgments provides.

    If none of the DDS.DataWriter instances 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_Participant (abstract) 

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

    Summary: Returns the DDS.DomainParticipant to which the DDS.Publisher belongs.

    self: <<in>> Cannot be NULL

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

    Set_Default_DataWriter_Qos (abstract) 

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

    Summary: Sets the default DDS.DataWriterQos values for this publisher.

    This call causes the default values inherited from the owning DDS.DomainParticipant to be overridden.

    This default value will be used for newly created DDS.DataWriter if DDS.DATAWRITER_QOS_DEFAULT is specified as the qos parameter when DDS.Publisher.create_datawriter is called.

    Precondition: The specified QoS policies must be consistent, or else the operation will have no effect and fail with DDS.RETCODE_INCONSISTENT_POLICY

    MT Safety:
    UNSAFE. It is not safe to set the default QoS value from a DDS.Publisher while another thread may be simultaneously calling DDS.Publisher.set_default_datawriter_qos, DDS.Publisher.get_default_datawriter_qos or calling DDS.Publisher.create_datawriter with DDS.DATAWRITER_QOS_DEFAULT as the qos parameter.

    self: <<in>> Cannot be NULL

    qos: <<in>> Default qos to be set. The special value DDS.DATAREADER_QOS_DEFAULT may be passed as qos to indicate that the default QoS should be reset back to the initial values the factory would used if DDS.Publisher.set_default_datawriter_qos had never been called. Cannot be NULL.

    Raises: One of the DDSReturnTypesModules_std_retcodes, or DDS.RETCODE_INCONSISTENT_POLICY

    Set_Default_DataWriter_Qos_With_Profile (abstract) 

    procedure Set_Default_DataWriter_Qos_With_Profile 
    (Self: not null access Ref;
    libName: DDS.String;
    profName: DDS.String) is abstract;

    Set_Default_DataWriter_Qos_With_Profile (abstract) 

    procedure Set_Default_DataWriter_Qos_With_Profile 
    (Self: not null access Ref;
    libName: Standard.String;
    profName: Standard.String) is abstract;

    Summary: <<ext>> Set the default DDS.DataWriterQos values for this publisher based on the input XML QoS profile.

    This default value will be used for newly created DDS.DataWriter if DDS.DATAWRITER_QOS_DEFAULT is specified as the qos parameter when DDS.Publisher.create_datawriter is called.

    Precondition: The DDS.DataWriterQos contained in the specified XML QoS profile must be consistent, or else the operation will have no effect and fail with DDS.RETCODE_INCONSISTENT_POLICY

    MT Safety:
    UNSAFE. It is not safe to set the default QoS value from a DDS.Publisher while another thread may be simultaneously calling DDS.Publisher.set_default_datawriter_qos, DDS.Publisher.get_default_datawriter_qos or calling DDS.Publisher.create_datawriter with DDS.DATAWRITER_QOS_DEFAULT as the qos parameter.

    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).

    If the input profile cannot be found, the procedure fails with DDS.RETCODE_ERROR.

    Raises: One of the DDSReturnTypesModules_std_retcodes, or DDS.RETCODE_INCONSISTENT_POLICY


    See also: DDS.DATAWRITER_QOS_DEFAULT
    See also: DDS.Publisher.create_datawriter_with_profile

    Get_Default_DataWriter_Qos (abstract) 

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

    Summary: Copies the default DDS.DataWriterQos values into the provided DDS.DataWriterQos instance.

    The retrieved qos will match the set of values specified on the last successful call to DDS.Publisher.set_default_datawriter_qos or DDS.Publisher.set_default_datawriter_qos_with_profile, or else, if the call was never made, the default values from its owning DDS.DomainParticipant.

    This procedure may potentially allocate memory depending on the sequences contained in some QoS policies.

    MT Safety:
    UNSAFE. It is not safe to retrieve the default QoS value from a DDS.Publisher while another thread may be simultaneously calling DDS.Publisher.set_default_datawriter_qos.

    self: <<in>> Cannot be NULL

    qos: <<inout>> DDS.DataWriterQos to be filled-up. Cannot be NULL.

    Raises: One of the DDSReturnTypesModules_std_retcodes


    See also: DDS.DATAWRITER_QOS_DEFAULT
    See also: DDS.Publisher.create_datawriter

    Copy_From_Topic_Qos (abstract) 

    procedure Copy_From_Topic_Qos 
    (Self: not null access Ref;
    A_DataWriter_Qos: in out DDS.DataWriterQos;
    A_Topic_Qos: in DDS.TopicQos) is abstract;

    Summary: Copies the policies in the DDS.TopicQos to the corresponding policies in the DDS.DataWriterQos

    Copies the policies in the DDS.TopicQos to the corresponding policies in the DDS.DataWriterQos (replacing values in the DDS.DataWriterQos, if present).

    This is a "convenience" operation most useful in combination with the operations DDS.Publisher.get_default_datawriter_qos and DDS.Topic.get_qos. The operation DDS.Publisher.copy_from_topic_qos can be used to merge the DDS.DataWriter default QoS policies with the corresponding ones on the DDS.Topic. The resulting QoS can then be used to create a new DDS.DataWriter, or set its QoS.

    This operation does not check the resulting DDS.DataWriterQos for consistency. This is because the 'merged' DDS.DataWriterQos may not be the final one, as the application can still modify some policies prior to applying the policies to the DDS.DataWriter.

    self: <<in>> Cannot be NULL

    a_datawriter_qos: <<inout>> DDS.DataWriterQos to be filled-up. Cannot be NULL.

    a_topic_qos: <<in>> DDS.TopicQos to be merged with DDS.DataWriterQos. Cannot be NULL.

    Raises: One of the DDSReturnTypesModules_std_retcodes

    Set_Default_Profile (abstract) 

    procedure Set_Default_Profile 
    (Self: not null access Ref;
    library_name: DDS.String;
    profile_name: DDS.String) is abstract;

    Summary: <<ext>> Sets the default XML profile for a DDS.Publisher.

    This procedure specifies the profile that will be used as the default the next time a default Publisher profile is needed during a call to one of this Publisher's operations. When calling a DDS.Publisher procedure that requires a profile_name parameter, you can use NULL to refer to the default profile. (This same information applies to setting a default library.)

    If the default profile is not set, the DDS.Publisher inherits the default from the DDS.DomainParticipant (see DDS.DomainParticipant.set_default_profile).

    This procedure does not set the default QoS for DDS.DataWriter objects created by the DDS.Publisher; for this functionality, use DDS.Publisher.set_default_datawriter_qos_with_profile (you may pass in NULL after having called set_default_profile()).

    This procedure does not set the default QoS for newly created Publishers; for this functionality, use DDS.DomainParticipant.set_default_publisher_qos_with_profile.

    self: <<in>> Cannot be NULL

    library_name: <<in>> The library name containing the profile.

    profile_name: <<in>> The profile name. If profile_name is null any previous default is unset.

    Raises: One of the DDSReturnTypesModules_std_retcodes


    See also: DDS.Publisher.get_default_profile
    See also: DDS.Publisher.get_default_profile_library

    Set_Default_Library (abstract) 

    procedure Set_Default_Library 
    (Self: not null access Ref;
    library_name: DDS.String) is abstract;

    Summary: <<ext>> Sets the default XML library for a DDS.Publisher.

    This procedure specifies the library that will be used as the default the next time a default library is needed during a call to one of this Publisher's operations.

    Any API requiring a library_name as a parameter can use null to refer to the default library.

    If the default library is not set, the DDS.Publisher inherits the default from the DDS.DomainParticipant (see DDS.DomainParticipant.set_default_library).

    self: <<in>> Cannot be NULL

    library_name: <<in>> Library name. If library_name is null any previous default is unset.

    Raises: One of the DDSReturnTypesModules_std_retcodes


    See also: DDS.Publisher.get_default_library

    Get_Default_Library (abstract) 

    function Get_Default_Library 
    (Self: not null access Ref) return DDS.String is abstract;

    Summary: <<ext>> Gets the default XML library associated with a DDS.Publisher.

    self: <<in>> Cannot be NULL

    Returns: The default library or null if the default library was not set.


    See also: DDS.Publisher.set_default_library

    Get_Default_Profile (abstract) 

    function Get_Default_Profile 
    (Self: not null access Ref) return DDS.String is abstract;

    Summary: <<ext>> Gets the default XML profile associated with a DDS.Publisher.

    self: <<in>> Cannot be NULL

    Returns: The default profile or null if the default profile was not set.


    See also: DDS.Publisher.set_default_profile

    Get_Default_Profile_Library (abstract) 

    function Get_Default_Profile_Library 
    (Self: not null access Ref) return DDS.String is abstract;

    Summary: <<ext>> Gets the library where the default XML QoS profile is contained for a DDS.Publisher.

    The default profile library is automatically set when DDS.Publisher.set_default_profile is called.

    This library can be different than the DDS.Publisher default library (see DDS.Publisher.get_default_library).

    self: <<in>> Cannot be NULL

    Returns: The default profile library or null if the default profile was not set.


    See also: DDS.Publisher.set_default_profile