|
RTI Connext DDS Micro
Version 2.4.8
|
|
RTI Connext DDS Micro
Version 2.4.8
|
DDS_DataReader entity and associated elements More...
Data Structures | |
| struct | FooDataReader |
| <<interface>> <<generic>> User data type-specific data reader. More... | |
| struct | DDS_RequestedDeadlineMissedStatus |
| <<cert>> DDS_REQUESTED_DEADLINE_MISSED_STATUS More... | |
| struct | DDS_LivelinessChangedStatus |
| <<cert>> DDS_LIVELINESS_CHANGED_STATUS More... | |
| struct | DDS_RequestedIncompatibleQosStatus |
| <<cert>> DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS More... | |
| struct | DDS_SampleRejectedStatus |
| DDS_SAMPLE_REJECTED_STATUS More... | |
| struct | DDS_DataReaderInstanceReplacedStatus |
| <<eXtension>> <<cert>> DDS_INSTANCE_REPLACED_STATUS. More... | |
| struct | DDS_SubscriptionMatchedStatus |
| <<cert>> DDS_SUBSCRIPTION_MATCHED_STATUS More... | |
| struct | DDS_SampleLostStatus |
| <<cert>> DDS_SAMPLE_LOST_STATUS More... | |
| struct | DDS_DataReaderQos |
| <<cert>> QoS policies supported by a DDS_DataReader entity. More... | |
| struct | DDS_DataReaderListener |
| <<interface>> <<cert>> DDS_Listener for reader status. More... | |
Macros | |
| #define | DDS_RequestedDeadlineMissedStatus_INITIALIZER |
| <<cert>> Initializer for new status instances. | |
| #define | DDS_LivelinessChangedStatus_INITIALIZER |
| <<cert>> Initializer for new status instances. | |
| #define | DDS_RequestedIncompatibleQosStatus_INITIALIZER |
| <<cert>> Initializer for new status instances. | |
| #define | DDS_SampleRejectedStatus_INITIALIZER |
| <<cert>> Initializer for new status instances. | |
| #define | DDS_DataReaderInstanceReplacedStatus_INITIALIZER |
| <<cert>> Initializer for new status instances. | |
| #define | DDS_SubscriptionMatchedStatus_INITIALIZER |
| <<cert>> Initializer for new status instances. | |
| #define | DDS_SampleLostStatus_INITIALIZER |
| <<cert>> Initializer for new status instances. | |
| #define | DDS_DataReaderQos_INITIALIZER |
| <<cert>> Initializer for new QoS instances. | |
| #define | DDS_DataReaderListener_INITIALIZER |
| <<cert>> Initializer for new DDS_DataReaderListener. | |
Typedefs | |
| typedef struct DDS_DataReaderImpl | DDS_DataReader |
| <<interface>> <<cert>> Allows the application to: (1) declare the data it wishes to receive (i.e. make a subscription) and (2) access the data received by the attached DDS_Subscriber. | |
| typedef void(* | DDS_DataReaderListener_RequestedDeadlineMissedCallback )(void *listener_data, DDS_DataReader *reader, const struct DDS_RequestedDeadlineMissedStatus *status) |
| <<cert>> Prototype of a DDS_DataReaderListener requested_deadline_missed function. | |
| typedef void(* | DDS_DataReaderListener_LivelinessChangedCallback )(void *listener_data, DDS_DataReader *reader, const struct DDS_LivelinessChangedStatus *status) |
| <<cert>> Prototype of a DDS_DataReaderListener liveliness_changed function. | |
| typedef void(* | DDS_DataReaderListener_RequestedIncompatibleQosCallback )(void *listener_data, DDS_DataReader *reader, const struct DDS_RequestedIncompatibleQosStatus *status) |
| <<cert>> Prototype of a DDS_DataReaderListener requested_incompatible_QoS function. | |
| typedef void(* | DDS_DataReaderListener_SampleRejectedCallback )(void *listener_data, DDS_DataReader *reader, const struct DDS_SampleRejectedStatus *status) |
| <<cert>> Prototype of a DDS_DataReaderListener sample_rejected function. | |
| typedef void(* | DDS_DataReaderListener_DataAvailableCallback )(void *listener_data, DDS_DataReader *reader) |
| <<cert>> Prototype of a DDS_DataReaderListener data_available function. | |
| typedef void(* | DDS_DataReaderListener_SubscriptionMatchedCallback )(void *listener_data, DDS_DataReader *reader, const struct DDS_SubscriptionMatchedStatus *status) |
| <<cert>> Prototype of a DDS_DataReaderListener subscription_match function. | |
| typedef void(* | DDS_DataReaderListener_SampleLostCallback )(void *listener_data, DDS_DataReader *reader, const struct DDS_SampleLostStatus *status) |
| <<cert>> Prototype of a DDS_DataReaderListener subscription_lost function. | |
| typedef void(* | DDS_DataReaderListener_InstanceReplacedCallback )(void *listener_data, DDS_DataReader *reader, const struct DDS_DataReaderInstanceReplacedStatus *status) |
| <<cert>> Prototype of a DDS_DataReaderListener instance_replaced function. | |
| typedef DDS_Boolean(* | DDS_DataReaderListener_BeforeSampleDeserializeCallback )(void *listener_data, DDS_DataReader *reader, struct NDDS_Type_Plugin *plugin, struct CDR_Stream_t *stream, DDS_Boolean *dropped) |
| <<cert>> Prototype of a DDS_DataReaderListener before_sample_deserialize function. | |
| typedef DDS_Boolean(* | DDS_DataReaderListener_BeforeSampleCommitCallback )(void *listener_data, DDS_DataReader *reader, const void *const sample, DDS_Boolean *dropped) |
| <<cert>> Prototype of a DDS_DataReaderListener before_sample_commit function. | |
Enumerations | |
| enum | DDS_SampleRejectedStatusKind { DDS_NOT_REJECTED, DDS_REJECTED_BY_INSTANCES_LIMIT, DDS_REJECTED_BY_SAMPLES_LIMIT, DDS_REJECTED_BY_SAMPLES_PER_INSTANCE_LIMIT, DDS_REJECTED_BY_REMOTE_WRITERS_LIMIT, DDS_REJECTED_BY_SAMPLES_PER_REMOTE_WRITER_LIMIT } |
| Kinds of reasons for rejecting a sample. More... | |
| enum | DDS_SampleLostStatusKind { DDS_SAMPLE_LOST_NOT_LOST, DDS_SAMPLE_LOST_BY_DATAWRITER, DDS_SAMPLE_LOST_BY_MAX_SAMPLES_LIMIT, DDS_SAMPLE_LOST_BY_HISTORY_DEPTH_LIMIT, DDS_SAMPLE_LOST_BY_META_SAMPLE_LIMIT, DDS_SAMPLE_LOST_BY_NOT_READ_ON_CACHE_DELETION } |
| Kinds of reasons a sample was lost. More... | |
DDS_DataReader entity and associated elements
| #define DDS_RequestedDeadlineMissedStatus_INITIALIZER |
<<cert>> Initializer for new status instances.
New DDS_RequestedDeadlineMissedStatus instances that are stored on the stack should be initialized with this value before they are passed to any methods. This step ensures that those fields that use dynamic memory are properly initialized. This does not allocate memory. The simplest way to create a status structure is to initialize it on the stack at the time of its creation.
| #define DDS_LivelinessChangedStatus_INITIALIZER |
<<cert>> Initializer for new status instances.
New DDS_LivelinessChangedStatus instances that are stored on the stack should be initialized with this value before they are passed to any function . This step ensures that those fields that use dynamic memory are properly initialized. This does not allocate memory. The simplest way to create a status structure is to initialize it on the stack at the time of its creation.
| #define DDS_RequestedIncompatibleQosStatus_INITIALIZER |
<<cert>> Initializer for new status instances.
New DDS_RequestedIncompatibleQosStatus instances that are stored on the stack should be initialized with this value before they are passed to any function . This step ensures that those fields that use dynamic memory are properly initialized. This does not allocate memory. The simplest way to create a status structure is to initialize it on the stack at the time of its creation.
| #define DDS_SampleRejectedStatus_INITIALIZER |
<<cert>> Initializer for new status instances.
New DDS_SampleRejectedStatus instances that are stored on the stack should be initialized with this value before they are passed to any function . This step ensures that those fields that use dynamic memory are properly initialized. This does not allocate memory. The simplest way to create a status structure is to initialize it on the stack at the time of its creation.
| #define DDS_DataReaderInstanceReplacedStatus_INITIALIZER |
<<cert>> Initializer for new status instances.
New DDS_DataReaderInstanceReplacedStatus instances that are stored on the stack should be initialized with this value before they are passed to any methods. This step ensures that those fields that use dynamic memory are properly initialized. This does not allocate memory. The simplest way to create a status structure is to initialize it on the stack at the time of its creation.
| #define DDS_SubscriptionMatchedStatus_INITIALIZER |
<<cert>> Initializer for new status instances.
New DDS_SubscriptionMatchedStatus instances that are stored on the stack should be initialized with this value before they are passed to any function . This step ensures that those fields that use dynamic memory are properly initialized. This does not allocate memory. The simplest way to create a status structure is to initialize it on the stack at the time of its creation.
| #define DDS_SampleLostStatus_INITIALIZER |
<<cert>> Initializer for new status instances.
New DDS_SampleLostStatus instances that are stored on the stack should be initialized with this value before they are passed to any function . This step ensures that those fields that use dynamic memory are properly initialized. This does not allocate memory. The simplest way to create a status structure is to initialize it on the stack at the time of its creation.
| #define DDS_DataReaderQos_INITIALIZER |
<<cert>> Initializer for new QoS instances.
New DDS_DataReaderQos instances that are stored in the stack should be initialized with this value before they are passed to any function . This step ensures that those contained QoS policies that use dynamic memory are properly initialized. The simplest way to create a new QoS structure is to initialize it on the stack at the time of its creation:
| #define DDS_DataReaderListener_INITIALIZER |
<<cert>> Initializer for new DDS_DataReaderListener.
All the new instances allocated in the stack should be initialized to this value.No memory is allocated.
| typedef struct DDS_DataReaderImpl DDS_DataReader |
<<interface>> <<cert>> Allows the application to: (1) declare the data it wishes to receive (i.e. make a subscription) and (2) access the data received by the attached DDS_Subscriber.
key. The following operations may be called even if the DDS_DataReader is not enabled. Other operations will fail with the value DDS_RETCODE_NOT_ENABLED if called on a disabled DDS_DataReader: | typedef void(* DDS_DataReaderListener_RequestedDeadlineMissedCallback)(void *listener_data, DDS_DataReader *reader, const struct DDS_RequestedDeadlineMissedStatus *status) |
<<cert>> Prototype of a DDS_DataReaderListener requested_deadline_missed function.
| typedef void(* DDS_DataReaderListener_LivelinessChangedCallback)(void *listener_data, DDS_DataReader *reader, const struct DDS_LivelinessChangedStatus *status) |
<<cert>> Prototype of a DDS_DataReaderListener liveliness_changed function.
| typedef void(* DDS_DataReaderListener_RequestedIncompatibleQosCallback)(void *listener_data, DDS_DataReader *reader, const struct DDS_RequestedIncompatibleQosStatus *status) |
<<cert>> Prototype of a DDS_DataReaderListener requested_incompatible_QoS function.
| typedef void(* DDS_DataReaderListener_SampleRejectedCallback)(void *listener_data, DDS_DataReader *reader, const struct DDS_SampleRejectedStatus *status) |
<<cert>> Prototype of a DDS_DataReaderListener sample_rejected function.
| typedef void(* DDS_DataReaderListener_DataAvailableCallback)(void *listener_data, DDS_DataReader *reader) |
<<cert>> Prototype of a DDS_DataReaderListener data_available function.
| typedef void(* DDS_DataReaderListener_SubscriptionMatchedCallback)(void *listener_data, DDS_DataReader *reader, const struct DDS_SubscriptionMatchedStatus *status) |
<<cert>> Prototype of a DDS_DataReaderListener subscription_match function.
| typedef void(* DDS_DataReaderListener_SampleLostCallback)(void *listener_data, DDS_DataReader *reader, const struct DDS_SampleLostStatus *status) |
<<cert>> Prototype of a DDS_DataReaderListener subscription_lost function.
| typedef void(* DDS_DataReaderListener_InstanceReplacedCallback)(void *listener_data, DDS_DataReader *reader, const struct DDS_DataReaderInstanceReplacedStatus *status) |
<<cert>> Prototype of a DDS_DataReaderListener instance_replaced function.
| typedef DDS_Boolean(* DDS_DataReaderListener_BeforeSampleDeserializeCallback)(void *listener_data, DDS_DataReader *reader, struct NDDS_Type_Plugin *plugin, struct CDR_Stream_t *stream, DDS_Boolean *dropped) |
<<cert>> Prototype of a DDS_DataReaderListener before_sample_deserialize function.
| typedef DDS_Boolean(* DDS_DataReaderListener_BeforeSampleCommitCallback)(void *listener_data, DDS_DataReader *reader, const void *const sample, DDS_Boolean *dropped) |
<<cert>> Prototype of a DDS_DataReaderListener before_sample_commit function.
Kinds of reasons for rejecting a sample.
| DDS_NOT_REJECTED |
Samples are never rejected.
|
| DDS_REJECTED_BY_INSTANCES_LIMIT |
A resource limit on the number of instances was reached.
|
| DDS_REJECTED_BY_SAMPLES_LIMIT |
A resource limit on the number of samples was reached.
|
| DDS_REJECTED_BY_SAMPLES_PER_INSTANCE_LIMIT |
A resource limit on the number of samples per instance was reached.
|
| DDS_REJECTED_BY_REMOTE_WRITERS_LIMIT |
A resource limit on the number of remote writers from which a DDS_DataReader may read was reached. This constant is an extension to the DDS standard. |
| DDS_REJECTED_BY_SAMPLES_PER_REMOTE_WRITER_LIMIT |
A resource limit on the number of samples from a given remote writer that a DDS_DataReader may store was reached. This constant is an extension to the DDS standard. |
Kinds of reasons a sample was lost.
| DDS_SAMPLE_LOST_NOT_LOST |
Samples was not lost, normal removal.
|
| DDS_SAMPLE_LOST_BY_DATAWRITER |
Samples was lost was by the datawriter, it was never received by the datareader.
|
| DDS_SAMPLE_LOST_BY_MAX_SAMPLES_LIMIT |
A sample was received by the datareader but lost because the max_samples resource was exceeded and not samples could be freed to receive it.
|
| DDS_SAMPLE_LOST_BY_HISTORY_DEPTH_LIMIT |
A sample was received by the datareader but lost because the max depth was reached for the instance and no samples could be removed from the history. For example if all the samples in the datareader cache is loanded by the application they cannot be removed.
|
| DDS_SAMPLE_LOST_BY_META_SAMPLE_LIMIT |
A meta sample was received by the datareader but lost because the meta sample for the instance was loaned by the application and could not be reused.
|
| DDS_SAMPLE_LOST_BY_NOT_READ_ON_CACHE_DELETION |
The datareader has samples in the cache that had not been seen by the application and was lost when the datareader was deleted.
|
| FooDataReader* FooDataReader_narrow | ( | DDS_DataReader * | reader | ) |
Narrow the given DDS_DataReader pointer to a FooDataReader pointer.
| reader | <<in>> Cannot be NULL. |
| DDS_DataReader* FooDataReader_as_datareader | ( | FooDataReader * | reader | ) |
Widen the given FooDataReader pointer to a DDS_DataReader pointer.
| reader | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t FooDataReader_read | ( | FooDataReader * | self, |
| struct FooSeq * | received_data, | ||
| struct DDS_SampleInfoSeq * | info_seq, | ||
| DDS_Long | max_samples, | ||
| DDS_SampleStateMask | sample_states, | ||
| DDS_ViewStateMask | view_states, | ||
| DDS_InstanceStateMask | instance_states | ||
| ) |
Access a collection of data samples from the DDS_DataReader.
This operation offers the same functionality and API as FooDataReader_take except that the samples returned remain in the DDS_DataReader such that they can be retrieved again by means of a read or take operation. Please refer to the documentation of FooDataReader_take() for details on the number of samples returned within the received_data and info_seq as well as the order in which the samples appear in these sequences. The act of reading a sample changes its sample_state to DDS_READ_SAMPLE_STATE. If the sample belongs to the most recent generation of the instance, it will also set the view_state of the instance to be DDS_NOT_NEW_VIEW_STATE. It will not affect the instance_state of the instance. Important: If the samples "returned" by this function are loaned from RTI Connext Micro (see FooDataReader_take for more information on memory loaning), it is important that their contents not be changed. Because the memory in which the data is stored belongs to the middleware, any modifications made to the data will be seen the next time the same samples are read or taken; the samples will no longer reflect the state that was received from the network.
| self | <<in>> Cannot be NULL. |
| received_data | <<inout>> User data type-specific FooSeq object where the received data samples will be returned. Must be a valid non-NULL FooSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| info_seq | <<inout>> A DDS_SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL DDS_SampleInfoSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| max_samples | <<in>> The maximum number of samples to be returned. If the special value DDS_LENGTH_UNLIMITED is provided, as many samples will be returned as are available. |
| sample_states | <<in>> Data samples matching one of these sample_states are returned. |
| view_states | <<in>> Data samples matching one of these view_state are returned. |
| instance_states | <<in>> Data samples matching ones of these instance_state are returned. |
| DDS_ReturnCode_t FooDataReader_take | ( | FooDataReader * | self, |
| struct FooSeq * | received_data, | ||
| struct DDS_SampleInfoSeq * | info_seq, | ||
| DDS_Long | max_samples, | ||
| DDS_SampleStateMask | sample_states, | ||
| DDS_ViewStateMask | view_states, | ||
| DDS_InstanceStateMask | instance_states | ||
| ) |
Access a collection of data-samples from the DDS_DataReader.
The operation will return the list of samples received by the DDS_DataReader since the last FooDataReader_take operation that match the specified DDS_SampleStateMask, DDS_ViewStateMask and DDS_InstanceStateMask.
view_state of the sample's instance to DDS_NOT_NEW_VIEW_STATE. It will not affect the instance_state of the sample's instance. After FooDataReader_take completes, received_data and info_seq will be of the same length and contain the received data. If the sequences are empty (maximum size equal 0) when the FooDataReader_take is called, the samples returned in the received_data and the corresponding info_seq are 'loaned' to the application from buffers provided by the DDS_DataReader. The application can use them as desired and has guaranteed exclusive access to them. Once the application completes its use of the samples it must 'return the loan' to the DDS_DataReader by calling the FooDataReader_return_loan operation. Note: While you must call FooDataReader_return_loan at some point, you do not have to do so before the next FooDataReader_take call. However, failure to return the loan will eventually deplete the DDS_DataReader of the buffers it needs to receive new samples and eventually samples will start to be lost. The total number of buffers available to the DDS_DataReader is specified by the DDS_ResourceLimitsQosPolicy. If the sequences are not empty (maximum size not equal 0) when the FooDataReader_take is called, samples are copied to received_data and info_seq. The application will not need to call FooDataReader_return_loan. The samples returned to the caller is a list where samples belonging to the same data instance are consecutive (i.e. instance access scope). Samples belonging to the same instance will appear in the relative order in which there were received (i.e. reception timestamp destination order, where earlier samples are ahead of later samples). If the DDS_DataReader has no samples that meet the constraints, the function will fail with DDS_RETCODE_NO_DATA. In addition to the collection of samples, the read and take operations also use a collection of DDS_SampleInfo structures. The initial (input) properties of the received_data and info_seq collections will determine the precise behavior of the read or take operation. For the purposes of this description, the collections are modeled as having these properties:
owns, see FooSeq_has_ownership) len, see FooSeq_get_length) max_len, see FooSeq_get_maximum) The initial values of the owns, len and max_len properties for the received_data and info_seq collections govern the behavior of the read and take operations as specified by the following rules: owns, len and max_len properties for the two collections must be identical. Otherwise read/take will fail with DDS_RETCODE_PRECONDITION_NOT_MET. owns, len and max_len will be the same for both collections. max_len==0, then the received_data and info_seq collections will be filled with elements that are loaned by the DDS_DataReader. On output, owns will be FALSE, len will be set to the number of values returned, and max_len will be set to a value verifying max_len >= len. The use of this variant allows for zero-copy access to the data and the application will need to return the loan to the DDS_DataWriter using FooDataReader_return_loan. max_len>0 and owns==FALSE, then the read or take operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET. This avoids the potential hard-to-detect memory leaks caused by an application forgetting to return the loan. max_len>0 and owns==TRUE, then the read or take operation will copy the received_data values and DDS_SampleInfo values into the elements already inside the collections. On output, owns will be TRUE, len will be set to the number of values copied and max_len will remain unchanged. The use of this variant forces a copy but the application can control where the copy is placed and the application will not need to return the loan. The number of samples copied depends on the relative values of max_len and max_samples: max_samples == LENGTH_UNLIMITED, then at most max_len values will be copied. The use of this variant lets the application limit the number of samples returned to what the sequence can accommodate. max_samples <= max_len, then at most max_samples values will be copied. The use of this variant lets the application limit the number of samples returned to fewer that what the sequence can accommodate. max_samples > max_len, then the read or take operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET. This avoids the potential confusion where the application expects to be able to access up to max_samples, but that number can never be returned, even if they are available in the DDS_DataReader, because the output sequence cannot accommodate them. received_data and info_seq collections may contain elements loaned from the DDS_DataReader. If this is the case, the application will need to use FooDataReader_return_loan to return the loan once it is no longer using the received_data in the collection. When FooDataReader_return_loan completes, the collection will have owns=FALSE and max_len=0. The application can determine whether it is necessary to return the loan or not based on how the state of the collections when the read/take operation was called or by accessing the owns property. However, in many cases it may be simpler to always call FooDataReader_return_loan, as this operation is harmless (i.e., it leaves all elements unchanged) if the collection does not have a loan. To avoid potential memory leaks, the implementation of the Foo and DDS_SampleInfo collections should disallow changing the length of a collection for which owns==FALSE. Furthermore, deleting a collection for which owns==FALSE should be considered an error. On output, the collection of Foo values and the collection of DDS_SampleInfo structures are of the same length and are in a one-to-one correspondence. Each DDS_SampleInfo provides information, such as the source_timestamp, the sample_state, view_state, and instance_state, etc., about the corresponding sample. Some elements in the returned collection may not have valid data. If the instance_state in the DDS_SampleInfo is DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE or DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE, then the last sample for that instance in the collection (that is, the one whose DDS_SampleInfo has sample_rank==0) does not contain valid data. Samples that contain no data do not count towards the limits imposed by the DDS_ResourceLimitsQosPolicy. The act of reading/taking a sample sets its sample_state to DDS_READ_SAMPLE_STATE. If the sample belongs to the most recent generation of the instance, it will also set the view_state of the instance to DDS_NOT_NEW_VIEW_STATE. It will not affect the instance_state of the instance. This operation must be provided on the specialized class that is generated for the particular application data-type that is being read (Foo). If the DDS_DataReader has no samples that meet the constraints, the operations fails with DDS_RETCODE_NO_DATA. | received_data | <<inout>> User data type-specific FooSeq object where the received data samples will be returned. Must be a valid non-NULL FooSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| self | <<in>> Cannot be NULL. |
| info_seq | <<inout>> A DDS_SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL DDS_SampleInfoSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| max_samples | <<in>> The maximum number of samples to be returned. If the special value DDS_LENGTH_UNLIMITED is provided, as many samples will be returned as are available. |
| sample_states | <<in>> Data samples matching one of these sample_states are returned. |
| view_states | <<in>> Data samples matching one of these view_state are returned. |
| instance_states | <<in>> Data samples matching one of these instance_state are returned. |
| DDS_ReturnCode_t FooDataReader_read_next_sample | ( | FooDataReader * | self, |
| struct Foo * | received_data, | ||
| struct DDS_SampleInfo * | sample_info | ||
| ) |
Copies the next not-previously-accessed data value from the DDS_DataReader.
This operation copies the next not-previously-accessed data value from the DDS_DataReader. This operation also copies the corresponding DDS_SampleInfo. The implied order among the samples stored in the DDS_DataReader is the same as for the FooDataReader_read operation. The FooDataReader_read_next_sample operation is semantically equivalent to the FooDataReader_read operation, where the input data sequences has max_len=1, the sample_states=NOT_READ, the view_states=ANY_VIEW_STATE, and the instance_states=ANY_INSTANCE_STATE. The FooDataReader_read_next_sample operation provides a simplified API to 'read' samples, avoiding the need for the application to manage sequences and specify states. If there is no unread data in the DDS_DataReader, the operation will fail with DDS_RETCODE_NO_DATA and nothing is copied.
| self | <<in>> Cannot be NULL. |
| received_data | <<inout>> user data type-specific Foo object where the next received data sample will be returned. The received_data must have been fully allocated. Otherwise, this operation may fail. Must be a valid non-NULL Foo. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| sample_info | <<inout>> a DDS_SampleInfo object where the next received sample info will be returned. Must be a valid non-NULL DDS_SampleInfo. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| DDS_ReturnCode_t FooDataReader_take_next_sample | ( | FooDataReader * | self, |
| struct Foo * | received_data, | ||
| struct DDS_SampleInfo * | sample_info | ||
| ) |
Copies the next not-previously-accessed data value from the DDS_DataReader.
This operation copies the next not-previously-accessed data value from the DDS_DataReader and 'removes' it from the DDS_DataReader so that it is no longer accessible. This operation also copies the corresponding DDS_SampleInfo. This operation is analogous to the FooDataReader_read_next_sample except for the fact that the sample is removed from the DDS_DataReader. The FooDataReader_take_next_sample operation is semantically equivalent to the FooDataReader_take operation, where the input data sequences has max_len=1, the sample_states=NOT_READ, the view_states=ANY_VIEW_STATE, and the instance_states=ANY_INSTANCE_STATE. The FooDataReader_read_next_sample operation provides a simplified API to 'take' samples, avoiding the need for the application to manage sequences and specify states. If there is no unread data in the DDS_DataReader, the operation will fail with DDS_RETCODE_NO_DATA and nothing is copied.
| self | <<in>> Cannot be NULL. |
| received_data | <<inout>> user data type-specific Foo object where the next received data sample will be returned. The received_data must have been fully allocated. Otherwise, this operation may fail. Must be a valid non-NULL Foo. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| sample_info | <<inout>> a DDS_SampleInfo object where the next received sample info will be returned. Must be a valid non-NULL DDS_SampleInfo. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| DDS_ReturnCode_t FooDataReader_read_instance | ( | FooDataReader * | self, |
| struct FooSeq * | received_data, | ||
| struct DDS_SampleInfoSeq * | info_seq, | ||
| DDS_Long | max_samples, | ||
| const DDS_InstanceHandle_t * | a_handle, | ||
| DDS_SampleStateMask | sample_states, | ||
| DDS_ViewStateMask | view_states, | ||
| DDS_InstanceStateMask | instance_states | ||
| ) |
Access a collection of data samples from the DDS_DataReader.
This operation accesses a collection of data values from the DDS_DataReader. The behavior is identical to FooDataReader_read, except that all samples returned belong to the single specified instance whose handle is a_handle. Upon successful completion, the data collection will contain samples all belonging to the same instance. The corresponding DDS_SampleInfo verifies DDS_SampleInfo::instance_handle == a_handle. The FooDataReader_read_instance operation is semantically equivalent to the FooDataReader_read operation, except in building the collection, the DDS_DataReader will check that the sample belongs to the specified instance and otherwise it will not place the sample in the returned collection. The behavior of the FooDataReader_read_instance operation follows the same rules as the FooDataReader_read operation regarding the pre-conditions and post-conditions for the received_data and sample_info. Similar to the FooDataReader_read, the FooDataReader_read_instance operation may 'loan' elements to the output collections, which must then be returned by means of FooDataReader_return_loan. Similar to the FooDataReader_read, this operation must be provided on the specialized class that is generated for the particular application data-type that is being taken. If the DDS_DataReader has no samples that meet the constraints, the function will fail with DDS_RETCODE_NO_DATA. This operation may fail with DDS_RETCODE_BAD_PARAMETER if the DDS_InstanceHandle_t a_handle does not correspond to an existing data-object known to the DDS_DataReader.
| self | <<in>> Cannot be NULL. |
| received_data | <<inout>> user data type-specific FooSeq object where the received data samples will be returned. Must be a valid non-NULL FooSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| info_seq | <<inout>> a DDS_SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL DDS_SampleInfoSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| max_samples | <<in>> The maximum number of samples to be returned. If the special value DDS_LENGTH_UNLIMITED is provided, as many samples will be returned as are available. |
| a_handle | <<in>> The specified instance to return samples for. Must be a valid non-NULL DDS_InstanceHandle_t. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL The function will fail with DDS_RETCODE_BAD_PARAMETER if the handle does not correspond to an existing data-object known to the DDS_DataReader. |
| sample_states | <<in>> data samples matching ones of these sample_states are returned |
| view_states | <<in>> data samples matching ones of these view_state are returned |
| instance_states | <<in>> data samples matching ones of these instance_state are returned |
| DDS_ReturnCode_t FooDataReader_take_instance | ( | FooDataReader * | self, |
| struct FooSeq * | received_data, | ||
| struct DDS_SampleInfoSeq * | info_seq, | ||
| DDS_Long | max_samples, | ||
| const DDS_InstanceHandle_t * | a_handle, | ||
| DDS_SampleStateMask | sample_states, | ||
| DDS_ViewStateMask | view_states, | ||
| DDS_InstanceStateMask | instance_states | ||
| ) |
Access a collection of data samples from the DDS_DataReader.
This operation accesses a collection of data values from the DDS_DataReader. The behavior is identical to FooDataReader_take, except for that all samples returned belong to the single specified instance whose handle is a_handle. The semantics are the same for the FooDataReader_take operation, except in building the collection, the DDS_DataReader will check that the sample belongs to the specified instance, and otherwise it will not place the sample in the returned collection. The behavior of the FooDataReader_take_instance operation follows the same rules as the FooDataReader_read operation regarding the pre-conditions and post-conditions for the received_data and sample_info. Similar to the FooDataReader_read, the FooDataReader_take_instance operation may 'loan' elements to the output collections, which must then be returned by means of FooDataReader_return_loan. Similar to the FooDataReader_read, this operation must be provided on the specialized class that is generated for the particular application data-type that is being taken. If the DDS_DataReader has no samples that meet the constraints, the function fails with DDS_RETCODE_NO_DATA. This operation may fail with DDS_RETCODE_BAD_PARAMETER if the DDS_InstanceHandle_t a_handle does not correspond to an existing data-object known to the DDS_DataReader.
| self | <<in>> Cannot be NULL. |
| received_data | <<inout>> user data type-specific FooSeq object where the received data samples will be returned. Must be a valid non-NULL FooSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| info_seq | <<inout>> a DDS_SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL DDS_SampleInfoSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| max_samples | <<in>> The maximum number of samples to be returned. If the special value DDS_LENGTH_UNLIMITED is provided, as many samples will be returned as are available. |
| a_handle | <<in>> The specified instance to return samples for. Must be a valid non-NULL DDS_InstanceHandle_t. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. The function will fail with DDS_RETCODE_BAD_PARAMETER if the handle does not correspond to an existing data-object known to the DDS_DataReader. |
| sample_states | <<in>> data samples matching ones of these sample_states are returned |
| view_states | <<in>> data samples matching ones of these view_state are returned |
| instance_states | <<in>> data samples matching ones of these instance_state are returned |
| DDS_ReturnCode_t FooDataReader_return_loan | ( | FooDataReader * | self, |
| FooSeq * | received_data, | ||
| struct DDS_SampleInfoSeq * | info_seq | ||
| ) |
Indicates to the DDS_DataReader that the application is done accessing the collection of received_data and info_seq obtained by some earlier invocation of read or take on the DDS_DataReader.
This operation indicates to the DDS_DataReader that the application is done accessing the collection of received_data and info_seq obtained by some earlier invocation of read or take on the DDS_DataReader. The received_data and info_seq must belong to a single related "pair"; that is, they should correspond to a pair returned from a single call to read or take. The received_data and info_seq must also have been obtained from the same DDS_DataReader to which they are returned. If either of these conditions is not met, the operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET. The operation FooDataReader_return_loan allows implementations of the read and take operations to "loan" buffers from the DDS_DataReader to the application and in this manner provide "zerocopy" access to the data. During the loan, the DDS_DataReader will guarantee that the data and sample-information are not modified. It is not necessary for an application to return the loans immediately after the read or take calls. However, as these buffers correspond to internal resources inside the DDS_DataReader, the application should not retain them indefinitely. The use of FooDataReader_return_loan is only necessary if the read or take calls "loaned" buffers to the application. This only occurs if the received_data and info_Seq collections had max_len=0 at the time read or take was called. The application may also examine the "owns" property of the collection to determine where there is an outstanding loan. However, calling FooDataReader_return_loan on a collection that does not have a loan is safe and has no side effects. If the collections had a loan, upon completion of FooDataReader_return_loan, the collections will have max_len=0. Similar to read, this operation must be provided on the specialized class that is generated for the particular application data-type that is being taken.
| received_data | <<in>> user data type-specific FooSeq object where the received data samples was obtained from earlier invocation of read or take on the DDS_DataReader. Must be a valid non-NULL FooSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| self | <<in>> Cannot be NULL. |
| info_seq | <<in>> a DDS_SampleInfoSeq object where the received sample info was obtained from earlier invocation of read or take on the DDS_DataReader. Must be a valid non-NULL DDS_SampleInfoSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| DDS_InstanceHandle_t FooDataReader_lookup_instance | ( | FooDataReader * | self, |
| const Foo * | key_holder | ||
| ) |
Retrieve the instance handle that corresponds to an instance key_holder.
Useful for keyed data types. This operation takes as a parameter an instance and returns a handle that can be used in subsequent operations that accept an instance handle as an argument. The instance parameter is only used for the purpose of examining the fields that define the key. This operation does not register the instance in question. If the instance has not been previously registered, or if for any other reason the Service is unable to provide an instance handle, the Service will return the special value HANDLE_NIL.
| DDS_ReturnCode_t DDS_DataReaderQos_initialize | ( | struct DDS_DataReaderQos * | self | ) |
Initializer for new QoS instances.
New DDS_DataReaderQos instances on the heap should be initialized with this function before they are passed to any function . This step ensures that those contained QoS policies that use dynamic memory are properly initialized. This function does not allocate memory.
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_DataReaderQos_copy | ( | struct DDS_DataReaderQos * | self, |
| const struct DDS_DataReaderQos * | source | ||
| ) |
Copy the contents of the given QoS into this QoS.
DDS_DataReaderQos instances can use dynamic memory because of the sequences contained in some QoS policies. A shallow copy by assignment is therefore unsafe. This function performs a deep-copy, allocating memory if necessary.
| DDS_ReturnCode_t DDS_DataReaderQos_finalize | ( | struct DDS_DataReaderQos * | self | ) |
Free any dynamic memory allocated by the policies in this DDS_DataReaderQos.
Some QoS policies may use dynamic memory (regardless of whether the QoS itself is in dynamic memory). This function frees that memory but otherwise leaves this QoS unchanged. It should be called on all instances before they are freed (or, in the case of stack-based instances, before they go out of scope). This function does not leave this object in an invalid state. It is permissable to clear a QoS and then subsequently allocate new dynamic memory in one or more of its QoS policies. Note that if this QoS instance is stored in heap memory, calling this function will not call free() on it; the user is responsible for explicitly freeing any heap-based QoS instance after calling this function .
| self | <<in>> Cannot be NULL. |
| DDS_Entity* DDS_DataReader_as_entity | ( | DDS_DataReader * | dataReader | ) |
<<cert>> Accesses the DDS_DataReader's supertype instance.
| dataReader | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_DataReader_enable | ( | DDS_Entity * | self | ) |
Enables a DDS_DataReader instance.
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_DataReader_get_matched_publications | ( | DDS_DataReader * | self, |
| struct DDS_InstanceHandleSeq * | publication_handles | ||
| ) |
Retrieve the list of publications currently "associated" with this DDS_DataReader.
Matching publications are those in the same domain that have a matching DDS_Topic, and compatible QoS common partition. The handles returned in the publication_handles' list are the ones that are used by the DDS implementation to locally identify the corresponding matched DDS_DataWriter entities. These handles match the ones that appear in the instance_handle field of the DDS_SampleInfo when reading the DDS_PUBLICATION_TOPIC_NAME builtin topic
| self | <<in>> Cannot be NULL. |
| publication_handles | inout. 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 function 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.. |
| DDS_ReturnCode_t DDS_DataReader_get_matched_publication_data | ( | DDS_DataReader * | self, |
| struct DDS_PublicationBuiltinTopicData * | publication_data, | ||
| const DDS_InstanceHandle_t * | publication_handle | ||
| ) |
This operation retrieves the information on a publication that is currently "associated" with the DDS_DataReader.
Publication with a matching DDS_Topic, compatible QoS and common partition. The publication_handle must correspond to a publication currently associated with the DDS_DataReader. Otherwise, the operation will fail with DDS_RETCODE_BAD_PARAMETER. Use the operation DDS_DataReader_get_matched_publications to find the publications that are currently matched with the DDS_DataReader.
| self | <<in>> Cannot be NULL. |
| publication_data | <<inout>>. The information to be filled in on the associated publication. Cannot be NULL. |
| publication_handle | <<in>>. Handle to a specific publication associated with the DDS_DataWriter. Cannot be NULL.. Must correspond to a publication currently associated with the DDS_DataReader. |
| DDS_TopicDescription* DDS_DataReader_get_topicdescription | ( | DDS_DataReader * | self | ) |
<<cert>> Returns the DDS_TopicDescription associated with the DDS_DataReader.
Returns that same DDS_TopicDescription that was used to create the DDS_DataReader.
| self | <<in>> Cannot be NULL. |
| DDS_Subscriber* DDS_DataReader_get_subscriber | ( | DDS_DataReader * | self | ) |
<<cert>> Returns the DDS_Subscriber to which the DDS_DataReader belongs.
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_DataReader_get_sample_rejected_status | ( | DDS_DataReader * | self, |
| struct DDS_SampleRejectedStatus * | status | ||
| ) |
<<cert>> Accesses the DDS_SAMPLE_REJECTED_STATUS communication status.
| self | <<in>> Cannot be NULL. |
| status | <<inout>> DDS_SampleRejectedStatus to be filled in. Cannot be NULL. |
| DDS_ReturnCode_t DDS_DataReader_get_liveliness_changed_status | ( | DDS_DataReader * | self, |
| struct DDS_LivelinessChangedStatus * | status | ||
| ) |
<<cert>> Accesses the DDS_LIVELINESS_CHANGED_STATUS communication status.
| self | <<in>> Cannot be NULL. |
| status | <<inout>> DDS_LivelinessChangedStatus to be filled in. Cannot be NULL. |
| DDS_ReturnCode_t DDS_DataReader_get_requested_deadline_missed_status | ( | DDS_DataReader * | self, |
| struct DDS_RequestedDeadlineMissedStatus * | status | ||
| ) |
<<cert>> Accesses the DDS_REQUESTED_DEADLINE_MISSED_STATUS communication status.
| self | <<in>> Cannot be NULL. |
| status | <<inout>> DDS_RequestedDeadlineMissedStatus to be filled in. Cannot be NULL. |
| DDS_ReturnCode_t DDS_DataReader_get_requested_incompatible_qos_status | ( | DDS_DataReader * | self, |
| struct DDS_RequestedIncompatibleQosStatus * | status | ||
| ) |
<<cert>> Accesses the DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS communication status.
| self | <<in>> Cannot be NULL. |
| status | <<inout>> DDS_RequestedIncompatibleQosStatus to be filled in. Cannot be NULL. |
| DDS_ReturnCode_t DDS_DataReader_get_subscription_matched_status | ( | DDS_DataReader * | self, |
| struct DDS_SubscriptionMatchedStatus * | status | ||
| ) |
<<cert>> Accesses the DDS_SUBSCRIPTION_MATCHED_STATUS communication status.
| self | <<in>> Cannot be NULL. |
| status | <<inout>> DDS_SubscriptionMatchedStatus to be filled in. Cannot be NULL. |
| DDS_ReturnCode_t DDS_DataReader_get_sample_lost_status | ( | DDS_DataReader * | self, |
| struct DDS_SampleLostStatus * | status | ||
| ) |
<<cert>> Accesses the DDS_SAMPLE_LOST_STATUS communication status.
| self | <<in>> Cannot be NULL. |
| status | <<inout>> DDS_SampleLostStatus to be filled in. Cannot be NULL. |
| DDS_ReturnCode_t DDS_DataReader_get_instance_replaced_status | ( | DDS_DataReader * | self, |
| struct DDS_DataReaderInstanceReplacedStatus * | status | ||
| ) |
<<cert>> Accesses the DDS_INSTANCE_REPLACED_STATUS communication status.
| self | <<in>> Cannot be NULL. |
| status | <<inout>> DDS_DataReaderInstanceReplacedStatus to be filled in. Cannot be NULL. |
| DDS_ReturnCode_t DDS_DataReader_set_qos | ( | DDS_DataReader * | self, |
| const struct DDS_DataReaderQos * | qos | ||
| ) |
Sets the reader QoS.
This operation modifies the QoS of the DDS_DataReader. The DDS_DataReaderQos::deadline can be changed. The other policies are immutable.
| self | <<in>> Cannot be NULL. |
| qos | <<in>> The DDS_DataReaderQos to be set to. Policies must be consistent. Policies cannot be changed after DDS_DataReader is enabled. The special value DDS_DATAREADER_QOS_DEFAULT can be used to indicate that the QoS of the DDS_DataReader should be changed to match the current default DDS_DataReaderQos set in the DDS_Subscriber. Cannot be NULL. |
| DDS_ReturnCode_t DDS_DataReader_get_qos | ( | DDS_DataReader * | self, |
| struct DDS_DataReaderQos * | qos | ||
| ) |
Gets the reader QoS.
This function may potentially allocate memory depending on the sequences contained in some QoS policies.
| self | <<in>> Cannot be NULL. |
| qos | <<inout>> The DDS_DataReaderQos to be filled up. Cannot be NULL. |
| DDS_ReturnCode_t DDS_DataReader_set_listener | ( | DDS_DataReader * | self, |
| const struct DDS_DataReaderListener * | l, | ||
| DDS_StatusMask | mask | ||
| ) |
Sets the reader listener.
| self | <<in>> Cannot be NULL. |
| l | <<in>> DDS_DataReaderListener to set to |
| mask | <<in>> DDS_StatusMask associated with the DDS_DataReaderListener. The callback function on the listener cannot be NULL if the corresponding status is turned on in the mask. |
|
read |
Get the reader listener.
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_DataReader_read | ( | DDS_DataReader * | self, |
| struct DDS_UntypedSampleSeq * | received_data, | ||
| struct DDS_SampleInfoSeq * | info_seq, | ||
| DDS_Long | max_samples, | ||
| DDS_SampleStateMask | sample_states, | ||
| DDS_ViewStateMask | view_states, | ||
| DDS_InstanceStateMask | instance_states | ||
| ) |
<<cert>> Access a collection of data samples from the DDS_DataReader.
This operation offers the same functionality and API as DDS_DataReader_take except that the samples returned remain in the DDS_DataReader such that they can be retrieved again by means of a read or take operation. Please refer to the documentation of DDS_DataReader_take() for details on the number of samples returned within the received_data and info_seq as well as the order in which the samples appear in these sequences. The act of reading a sample changes its sample_state to DDS_READ_SAMPLE_STATE. If the sample belongs to the most recent generation of the instance, it will also set the view_state of the instance to be DDS_NOT_NEW_VIEW_STATE. It will not affect the instance_state of the instance. Important: If the samples "returned" by this function are loaned from RTI Connext Micro (see DDS_DataReader_take for more information on memory loaning), it is important that their contents not be changed. Because the memory in which the data is stored belongs to the middleware, any modifications made to the data will be seen the next time the same samples are read or taken; the samples will no longer reflect the state that was received from the network.
| self | <<in>> Cannot be NULL. |
| received_data | <<inout>> User data untyped pointer where the received data samples will be returned. Must be a valid non-NULL pointer. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| info_seq | <<inout>> A DDS_SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL DDS_SampleInfoSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| max_samples | <<in>> The maximum number of samples to be returned. If the special value DDS_LENGTH_UNLIMITED is provided, as many samples will be returned as are available. |
| sample_states | <<in>> Data samples matching one of these sample_states are returned. |
| view_states | <<in>> Data samples matching one of these view_state are returned. |
| instance_states | <<in>> Data samples matching ones of these instance_state are returned. |
| DDS_ReturnCode_t DDS_DataReader_take | ( | DDS_DataReader * | self, |
| struct DDS_UntypedSampleSeq * | received_data, | ||
| struct DDS_SampleInfoSeq * | info_seq, | ||
| DDS_Long | max_samples, | ||
| DDS_SampleStateMask | sample_states, | ||
| DDS_ViewStateMask | view_states, | ||
| DDS_InstanceStateMask | instance_states | ||
| ) |
<<cert>> Access a collection of data-samples from the DDS_DataReader.
The operation will return the list of samples received by the DDS_DataReader since the last DDS_DataReader_take operation that match the specified DDS_SampleStateMask, DDS_ViewStateMask and DDS_InstanceStateMask. This operation may fail with DDS_RETCODE_ERROR if DDS_DataReaderResourceLimitsQosPolicy::max_outstanding_reads limit has been exceeded. The actual number of samples returned depends on the information that has been received by the middleware as well as the DDS_HistoryQosPolicy, DDS_ResourceLimitsQosPolicy, DDS_DataReaderResourceLimitsQosPolicy and the characteristics of the data-type that is associated with the DDS_DataReader:
view_state of the sample's instance to DDS_NOT_NEW_VIEW_STATE. It will not affect the instance_state of the sample's instance. After DDS_DataReader_take completes, received_data and info_seq will be of the same length and contain the received data. If the sequences are empty (maximum size equal 0) when the DDS_DataReader_take is called, the samples returned in the received_data and the corresponding info_seq are 'loaned' to the application from buffers provided by the DDS_DataReader. The application can use them as desired and has guaranteed exclusive access to them. Once the application completes its use of the samples it must 'return the loan' to the DDS_DataReader by calling the DDS_DataReader_return_loan operation. Note: While you must call DDS_DataReader_return_loan at some point, you do not have to do so before the next DDS_DataReader_take call. However, failure to return the loan will eventually deplete the DDS_DataReader of the buffers it needs to receive new samples and eventually samples will start to be lost. The total number of buffers available to the DDS_DataReader is specified by the DDS_ResourceLimitsQosPolicy and the DDS_DataReaderResourceLimitsQosPolicy. If the sequences are not empty (maximum size not equal 0) when the DDS_DataReader_take is called, samples are copied to received_data and info_seq. The application will not need to call FooDataReader_return_loan. If the DDS_DataReader has no samples that meet the constraints, the function will fail with DDS_RETCODE_NO_DATA. In addition to the collection of samples, the read and take operations also use a collection of DDS_SampleInfo structures. The initial (input) properties of the received_data and info_seq collections will determine the precise behavior of the read or take operation. For the purposes of this description, the collections are modeled as having these properties:
owns, see FooSeq_has_ownership) len, see FooSeq_get_length) max_len, see FooSeq_get_maximum) The initial values of the owns, len and max_len properties for the received_data and info_seq collections govern the behavior of the read and take operations as specified by the following rules: owns, len and max_len properties for the two collections must be identical. Otherwise read/take will fail with DDS_RETCODE_PRECONDITION_NOT_MET. owns, len and max_len will be the same for both collections. max_len==0, then the received_data and info_seq collections will be filled with elements that are loaned by the DDS_DataReader. On output, owns will be FALSE, len will be set to the number of values returned, and max_len will be set to a value verifying max_len >= len. The use of this variant allows for zero-copy access to the data and the application will need to return the loan to the DDS_DataWriter using FooDataReader_return_loan. max_len>0 and owns==FALSE, then the read or take operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET. This avoids the potential hard-to-detect memory leaks caused by an application forgetting to return the loan. max_len>0 and owns==TRUE, then the read or take operation will copy the received_data values and DDS_SampleInfo values into the elements already inside the collections. On output, owns will be TRUE, len will be set to the number of values copied and max_len will remain unchanged. The use of this variant forces a copy but the application can control where the copy is placed and the application will not need to return the loan. The number of samples copied depends on the relative values of max_len and max_samples: max_samples == LENGTH_UNLIMITED, then at most max_len values will be copied. The use of this variant lets the application limit the number of samples returned to what the sequence can accommodate. max_samples <= max_len, then at most max_samples values will be copied. The use of this variant lets the application limit the number of samples returned to fewer that what the sequence can accommodate. max_samples > max_len, then the read or take operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET. This avoids the potential confusion where the application expects to be able to access up to max_samples, but that number can never be returned, even if they are available in the DDS_DataReader, because the output sequence cannot accommodate them. received_data and info_seq collections may contain elements loaned from the DDS_DataReader. If this is the case, the application will need to use DDS_DataReader_return_loan to return the loan once it is no longer using the received_data in the collection. When DDS_DataReader_return_loan completes, the collection will have owns=FALSE and max_len=0. The application can determine whether it is necessary to return the loan or not based on how the state of the collections when the read/take operation was called or by accessing the owns property. However, in many cases it may be simpler to always call DDS_DataReader_return_loan, as this operation is harmless (i.e., it leaves all elements unchanged) if the collection does not have a loan. To avoid potential memory leaks, the implementation of the Foo and DDS_SampleInfo collections should disallow changing the length of a collection for which owns==FALSE. Furthermore, deleting a collection for which owns==FALSE should be considered an error. On output, the collection of Foo values and the collection of DDS_SampleInfo structures are of the same length and are in a one-to-one correspondence. Each DDS_SampleInfo provides information, such as the source_timestamp, the sample_state, view_state, and instance_state, etc., about the corresponding sample. Some elements in the returned collection may not have valid data. If the instance_state in the DDS_SampleInfo is DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE or DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE, then the last sample for that instance in the collection (that is, the one whose DDS_SampleInfo has sample_rank==0) does not contain valid data. Samples that contain no data do not count towards the limits imposed by the DDS_ResourceLimitsQosPolicy. The act of reading/taking a sample sets its sample_state to DDS_READ_SAMPLE_STATE. If the sample belongs to the most recent generation of the instance, it will also set the view_state of the instance to DDS_NOT_NEW_VIEW_STATE. It will not affect the instance_state of the instance. This operation must be provided on the specialized class that is generated for the particular application data-type that is being read . If the DDS_DataReader has no samples that meet the constraints, the operations fails with DDS_RETCODE_NO_DATA. | received_data | <<inout>> User data untyped pointer where the received data samples will be returned. Must be a valid non-NULL FooSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| self | <<in>> Cannot be NULL. |
| info_seq | <<inout>> A DDS_SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL DDS_SampleInfoSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| max_samples | <<in>> The maximum number of samples to be returned. If the special value DDS_LENGTH_UNLIMITED is provided, as many samples will be returned as are available. |
| sample_states | <<in>> Data samples matching one of these sample_states are returned. |
| view_states | <<in>> Data samples matching one of these view_state are returned. |
| instance_states | <<in>> Data samples matching one of these instance_state are returned. |
| DDS_ReturnCode_t DDS_DataReader_read_next_sample | ( | DDS_DataReader * | self, |
| void * | received_data, | ||
| struct DDS_SampleInfo * | sample_info | ||
| ) |
<<cert>> Copies the next not-previously-accessed data value from the DDS_DataReader.
This operation copies the next not-previously-accessed data value from the DDS_DataReader. This operation also copies the corresponding DDS_SampleInfo. The implied order among the samples stored in the DDS_DataReader is the same as for the DDS_DataReader_read operation. The DDS_DataReader_read_next_sample operation is semantically equivalent to the DDS_DataReader_read operation, where the input data sequences has max_len=1, the sample_states=NOT_READ, the view_states=ANY_VIEW_STATE, and the instance_states=ANY_INSTANCE_STATE. The DDS_DataReader_read_next_sample operation provides a simplified API to 'read' samples, avoiding the need for the application to manage sequences and specify states. If there is no unread data in the DDS_DataReader, the operation will fail with DDS_RETCODE_NO_DATA and nothing is copied.
| self | <<in>> Cannot be NULL. |
| received_data | <<inout>> user data type-specific data object where the next received data sample will be returned. The received_data must have been fully allocated. Otherwise, this operation may fail. Must be a valid non-NULL Data. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| sample_info | <<inout>> a DDS_SampleInfo object where the next received sample info will be returned. Must be a valid non-NULL DDS_SampleInfo. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| DDS_ReturnCode_t DDS_DataReader_take_next_sample | ( | DDS_DataReader * | self, |
| void * | received_data, | ||
| struct DDS_SampleInfo * | sample_info | ||
| ) |
<<cert>> Copies the next not-previously-accessed data value from the DDS_DataReader.
This operation copies the next not-previously-accessed data value from the DDS_DataReader and 'removes' it from the DDS_DataReader so that it is no longer accessible. This operation also copies the corresponding DDS_SampleInfo. This operation is analogous to the DDS_DataReader_read_next_sample except for the fact that the sample is removed from the DDS_DataReader. The DDS_DataReader_take_next_sample operation is semantically equivalent to the DDS_DataReader_take operation, where the input data sequences has max_len=1, the sample_states=NOT_READ, the view_states=ANY_VIEW_STATE, and the instance_states=ANY_INSTANCE_STATE. The DDS_DataReader_take_next_sample operation provides a simplified API to 'take' samples, avoiding the need for the application to manage sequences and specify states. If there is no unread data in the DDS_DataReader, the operation will fail with DDS_RETCODE_NO_DATA and nothing is copied.
| self | <<in>> Cannot be NULL. |
| received_data | <<inout>> user data type-specific Data object where the next received data sample will be returned. The received_data must have been fully allocated. Otherwise, this operation may fail. Must be a valid non-NULL Data. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| sample_info | <<inout>> a DDS_SampleInfo object where the next received sample info will be returned. Must be a valid non-NULL DDS_SampleInfo. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| DDS_ReturnCode_t DDS_DataReader_read_instance | ( | DDS_DataReader * | self, |
| struct DDS_UntypedSampleSeq * | received_data, | ||
| struct DDS_SampleInfoSeq * | info_seq, | ||
| DDS_Long | max_samples, | ||
| const DDS_InstanceHandle_t * | a_handle, | ||
| DDS_SampleStateMask | sample_states, | ||
| DDS_ViewStateMask | view_states, | ||
| DDS_InstanceStateMask | instance_states | ||
| ) |
<<cert>> Access a collection of data samples from the DDS_DataReader, all of which belong to the same instance .
| self | <<in>> Cannot be NULL. |
| received_data | <<inout>> User data untyped pointer where the received data samples will be returned. Must be a valid non-NULL pointer. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| info_seq | <<inout>> A DDS_SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL DDS_SampleInfoSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| max_samples | <<in>> The maximum number of samples to be returned. If the special value DDS_LENGTH_UNLIMITED is provided, as many samples will be returned as are available. |
| a_handle | <<in>> Instance for which data samples should be read |
| sample_states | <<in>> Data samples matching one of these sample_states are returned. |
| view_states | <<in>> Data samples matching one of these view_state are returned. |
| instance_states | <<in>> Data samples matching ones of these instance_state are returned. |
| DDS_ReturnCode_t DDS_DataReader_take_instance | ( | DDS_DataReader * | self, |
| struct DDS_UntypedSampleSeq * | received_data, | ||
| struct DDS_SampleInfoSeq * | info_seq, | ||
| DDS_Long | max_samples, | ||
| const DDS_InstanceHandle_t * | a_handle, | ||
| DDS_SampleStateMask | sample_states, | ||
| DDS_ViewStateMask | view_states, | ||
| DDS_InstanceStateMask | instance_states | ||
| ) |
<<cert>> Access a collection of data samples from the DDS_DataReader, all of which belong to the same instance .
| self | <<in>> Cannot be NULL. |
| received_data | <<inout>> User data untyped pointer where the received data samples will be returned. Must be a valid non-NULL pointer. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| info_seq | <<inout>> A DDS_SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL DDS_SampleInfoSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| max_samples | <<in>> The maximum number of samples to be returned. If the special value DDS_LENGTH_UNLIMITED is provided, as many samples will be returned as are available. |
| a_handle | <<in>> Instance for which data samples should be read |
| sample_states | <<in>> Data samples matching one of these sample_states are returned. |
| view_states | <<in>> Data samples matching one of these view_state are returned. |
| instance_states | <<in>> Data samples matching ones of these instance_state are returned. |
| DDS_ReturnCode_t DDS_DataReader_return_loan | ( | DDS_DataReader * | self, |
| struct DDS_UntypedSampleSeq * | received_data, | ||
| struct DDS_SampleInfoSeq * | info_seq | ||
| ) |
<<cert>> Indicates to the DDS_DataReader that the application is done accessing the collection of received_data and info_seq obtained by some earlier invocation of read or take on the DDS_DataReader.
This operation indicates to the DDS_DataReader that the application is done accessing the collection of received_data and info_seq obtained by some earlier invocation of read or take on the DDS_DataReader. The received_data and info_seq must belong to a single related "pair"; that is, they should correspond to a pair returned from a single call to read or take. The received_data and info_seq must also have been obtained from the same DDS_DataReader to which they are returned. If either of these conditions is not met, the operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET. The operation DDS_DataReader_return_loan allows implementations of the read and take operations to "loan" buffers from the DDS_DataReader to the application and in this manner provide "zerocopy" access to the data. During the loan, the DDS_DataReader will guarantee that the data and sample-information are not modified. It is not necessary for an application to return the loans immediately after the read or take calls. However, as these buffers correspond to internal resources inside the DDS_DataReader, the application should not retain them indefinitely. The use of DDS_DataReader_return_loan is only necessary if the read or take calls "loaned" buffers to the application. This only occurs if the received_data and info_Seq collections had max_len=0 at the time read or take was called. The application may also examine the "owns" property of the collection to determine where there is an outstanding loan. However, calling DDS_DataReader_return_loan on a collection that does not have a loan is safe and has no side effects. If the collections had a loan, upon completion of DDS_DataReader_return_loan, the collections will have max_len=0.
| received_data | <<in>> user data type-specific FooSeq object where the received data samples was obtained from earlier invocation of read or take on the DDS_DataReader. Must be a valid non-NULL FooSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| self | <<in>> Cannot be NULL. |
| info_seq | <<in>> a DDS_SampleInfoSeq object where the received sample info was obtained from earlier invocation of read or take on the DDS_DataReader. Must be a valid non-NULL DDS_SampleInfoSeq. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| DDS_InstanceHandle_t DDS_DataReader_lookup_instance | ( | DDS_DataReader * | self, |
| const void * | key_holder | ||
| ) |
<<cert>> Retrieve the DDS_InstanceHandle_t identifying a specific instance.
| self | <<in>> Cannot be NULL. |
| key_holder | <<in>> A data sample containing the desired values for key attributes. |
RTI Connext DDS Micro Version 2.4.8
Copyright © Tue Apr 12 2016
Real-Time Innovations, Inc