|
RTI Connext DDS Micro C API
Version 3.0.3
|
|
RTI Connext DDS Micro C API
Version 3.0.3
|
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, const struct DDS_SampleInfo *const sample_info, 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.
A DDS_DataReader refers to exactly one DDS_TopicDescription (a DDS_Topic) that identifies the data to be read.
The subscription has a unique resulting type. The data-reader may give access to several instances of the resulting type, which can be distinguished from each other by their 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, const struct DDS_SampleInfo *const sample_info, 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 DDS 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.
If the read or take succeeds and the number of samples returned has been limited (by means of a maximum limit, as listed above, or insufficient DDS_SampleInfo resources), the call will complete successfully and provide those samples the reader is able to return. The user may need to make additional calls, or return outstanding loaned buffers in the case of insuffificient resources, in order to access remaining samples.
Note that in the case where the DDS_Topic associated with the DDS_DataReader is bound to a data-type that has no key definition, then there will be at most one instance in the DDS_DataReader. So the per-sample limits will apply.
The act of taking a sample removes it from RTI Connext DDS Micro so it cannot be read or taken again. If the sample belongs to the most recent generation of the instance, it will also set the 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:
The values of owns, len and max_len properties for the two collections must be identical. Otherwise read/take will fail with DDS_RETCODE_PRECONDITION_NOT_MET.
On successful output, the values of owns, len and max_len will be the same for both collections.
If the initial 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.
If the initial 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.
If initial 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:
If 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.
If 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. As described above, upon completion, the 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 FooDataReader_is_data_consistent | ( | DDS_DataReader * | self, |
| DDS_Boolean * | is_data_consistent, | ||
| const Foo * | sample, | ||
| const struct DDS_SampleInfo * | sample_info | ||
| ) |
Checks if the sample has been overwritten by the DataWriter.
When a sample is received via Zero Copy transfer over shared memory, the sample can be reused by the DataWriter once it is removed from the DataWriter's send queue. Since there is no synchronization between the DataReader and the DataWriter, the sample could be overwritten by the DataWriter before it is processed by the DataReader. The FooDataReader_is_data_consistent operation can be used after processing the sample to check if it was overwritten by the DataWriter.
A precondition for using this operation is to set DDS_DataWriterShmemRefTransferModeSettings::enable_data_consistency_check to true.
| self | <<in>> Cannot be NULL. |
| is_data_consistent | <<inout>> Set to true if the sample is consistent (i.e., the sample has not been overwritten by the DataWriter) |
| sample | <<in>> Sample to be validated |
| sample_info | <<in>> DDS_SampleInfo object received with the sample |
| 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 * | self | ) |
<<cert>> Accesses the DDS_DataReader's supertype instance.
| self | <<in>> Cannot be NULL. |
| 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 * | listener, | ||
| DDS_StatusMask | mask | ||
| ) |
Sets the reader listener.
| self | <<in>> Cannot be NULL. |
| listener | <<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. |
RTI Connext DDS Micro C API Version 3.0.3
Copyright © Wed Jun 24 2020
Real-Time Innovations, Inc