|
RTI Connext C API
Version 5.2.3
|
|
RTI Connext C API
Version 5.2.3
|
DDS_DataReader entity and associated elements More...
Modules | |
| Read Conditions | |
| DDS_ReadCondition and associated elements | |
| Query Conditions | |
| DDS_QueryCondition and associated elements | |
Macros | |
| #define | DDS_RequestedDeadlineMissedStatus_INITIALIZER |
| Initializer for new status instances. | |
| #define | DDS_LivelinessChangedStatus_INITIALIZER |
| Initializer for new status instances. | |
| #define | DDS_RequestedIncompatibleQosStatus_INITIALIZER |
| Initializer for new status instances. | |
| #define | DDS_SampleLostStatus_INITIALIZER |
| Initializer for new status instances. | |
| #define | DDS_SampleRejectedStatus_INITIALIZER |
| Initializer for new status instances. | |
| #define | DDS_SubscriptionMatchedStatus_INITIALIZER |
| Initializer for new status instances. | |
| #define | DDS_DataReaderCacheStatus_INITIALIZER |
| Initializer for new status instances. | |
| #define | DDS_DataReaderProtocolStatus_INITIALIZER |
| Initializer for new status instances. | |
| #define | DDS_DataReaderQos_INITIALIZER |
| Initializer for new QoS instances. | |
| #define | DDS_DataReaderListener_INITIALIZER |
| Initializer for new DDS_DataReaderListener. | |
Typedefs | |
| typedef struct DDS_DataReaderImpl | DDS_DataReader |
| <<interface>> 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) |
| 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) |
| Prototype of a DDS_DataReaderListener liveliness_changed function. | |
| typedef void(* | DDS_DataReaderListener_RequestedIncompatibleQosCallback )(void *listener_data, DDS_DataReader *reader, const struct DDS_RequestedIncompatibleQosStatus *status) |
| 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) |
| Prototype of a DDS_DataReaderListener sample_rejected function. | |
| typedef void(* | DDS_DataReaderListener_DataAvailableCallback )(void *listener_data, DDS_DataReader *reader) |
| Prototype of a DDS_DataReaderListener data_available function. | |
| typedef void(* | DDS_DataReaderListener_SubscriptionMatchedCallback )(void *listener_data, DDS_DataReader *reader, const struct DDS_SubscriptionMatchedStatus *status) |
| Prototype of a DDS_DataReaderListener subscription_match function. | |
| typedef void(* | DDS_DataReaderListener_SampleLostCallback )(void *listener_data, DDS_DataReader *reader, const struct DDS_SampleLostStatus *status) |
| Prototype of a DDS_DataReaderListener subscription_lost function. | |
DDS_DataReader entity and associated elements
| #define DDS_RequestedDeadlineMissedStatus_INITIALIZER |
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. DDS_InconsistentTopicStatus_finalize should be called to free the contained fields that use dynamic memory:
| #define DDS_LivelinessChangedStatus_INITIALIZER |
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. DDS_LivelinessChangedStatus_finalize should be called to free the contained fields that use dynamic memory:
| #define DDS_RequestedIncompatibleQosStatus_INITIALIZER |
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. DDS_RequestedIncompatibleQosStatus_finalize should be called to free the contained fields that use dynamic memory:
| #define DDS_SampleLostStatus_INITIALIZER |
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. DDS_SampleLostStatus_finalize should be called to free the contained fields that use dynamic memory:
| #define DDS_SampleRejectedStatus_INITIALIZER |
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. DDS_SampleRejectedStatus_finalize should be called to free the contained fields that use dynamic memory:
| #define DDS_SubscriptionMatchedStatus_INITIALIZER |
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. DDS_SubscriptionMatchedStatus_finalize should be called to free the contained fields that use dynamic memory:
| #define DDS_DataReaderCacheStatus_INITIALIZER |
Initializer for new status instances.
New DDS_DataReaderCacheStatus instances 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. DDS_DataReaderCacheStatus_finalize should be called to free the contained fields that use dynamic memory:
| #define DDS_DataReaderProtocolStatus_INITIALIZER |
Initializer for new status instances.
New DDS_DataReaderProtocolStatus instances 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. DDS_DataReaderProtocolStatus_finalize should be called to free the contained fields that use dynamic memory:
| #define DDS_DataReaderQos_INITIALIZER |
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:
Note that the above assignment is not a substitute for calling DDS_Subscriber_get_default_datareader_qos or DDS_DataReader_get_qos; one of those should be called subsequently to setting the QoS of a new or existing entity:
| #define DDS_DataReaderListener_INITIALIZER |
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>> 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 (either a DDS_Topic, a DDS_ContentFilteredTopic or a DDS_MultiTopic) 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.
DDS_DataReader is an abstract class. It must be specialised for each particular application data-type (see USER_DATA). The additional methods or functions that must be defined in the auto-generated class for a hypothetical application type Foo are specified in the generic type FooDataReader.
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:
All sample-accessing operations, namely: FooDataReader_read, FooDataReader_take, FooDataReader_read_w_condition, and FooDataReader_take_w_condition may fail with the error DDS_RETCODE_PRECONDITION_NOT_MET as described in DDS_Subscriber_begin_access.
| typedef void(* DDS_DataReaderListener_RequestedDeadlineMissedCallback)(void *listener_data, DDS_DataReader *reader, const struct DDS_RequestedDeadlineMissedStatus *status) |
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) |
Prototype of a DDS_DataReaderListener liveliness_changed function.
| typedef void(* DDS_DataReaderListener_RequestedIncompatibleQosCallback)(void *listener_data, DDS_DataReader *reader, const struct DDS_RequestedIncompatibleQosStatus *status) |
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) |
Prototype of a DDS_DataReaderListener sample_rejected function.
| typedef void(* DDS_DataReaderListener_DataAvailableCallback)(void *listener_data, DDS_DataReader *reader) |
Prototype of a DDS_DataReaderListener data_available function.
| typedef void(* DDS_DataReaderListener_SubscriptionMatchedCallback)(void *listener_data, DDS_DataReader *reader, const struct DDS_SubscriptionMatchedStatus *status) |
Prototype of a DDS_DataReaderListener subscription_match function.
| typedef void(* DDS_DataReaderListener_SampleLostCallback)(void *listener_data, DDS_DataReader *reader, const struct DDS_SampleLostStatus *status) |
Prototype of a DDS_DataReaderListener subscription_lost function.
<<extension>> Kinds of reasons why a sample was lost.
| DDS_NOT_LOST |
The sample was not lost. This constant is an extension to the DDS standard.
|
| DDS_LOST_BY_WRITER |
A DDS_DataWriter removed the sample before being received by the DDS_DataReader. This constant is an extension to the DDS standard. |
| DDS_LOST_BY_INSTANCES_LIMIT |
A resource limit on the number of instances was reached. This constant is an extension to the DDS standard.
|
| DDS_LOST_BY_REMOTE_WRITERS_PER_INSTANCE_LIMIT |
A resource limit on the number of remote writers for a single instance from which a DDS_DataReader may read was reached. This constant is an extension to the DDS standard. |
| DDS_LOST_BY_INCOMPLETE_COHERENT_SET |
A sample is lost because it is part of an incomplete coherent set. This constant is an extension to the DDS standard. |
| DDS_LOST_BY_LARGE_COHERENT_SET |
A sample is lost because it is part of a large coherent set. This constant is an extension to the DDS standard. |
| DDS_LOST_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. |
| DDS_LOST_BY_VIRTUAL_WRITERS_LIMIT |
A resource limit on the number of virtual writers from which a DDS_DataReader may read was reached. This constant is an extension to the DDS standard. |
| DDS_LOST_BY_REMOTE_WRITERS_PER_SAMPLE_LIMIT |
A resource limit on the number of remote writers per sample was reached. This constant is an extension to the DDS standard. |
| DDS_LOST_BY_AVAILABILITY_WAITING_TIME |
DDS_AvailabilityQosPolicy::max_data_availability_waiting_time expired. This constant is an extension to the DDS standard. |
| DDS_LOST_BY_REMOTE_WRITER_SAMPLES_PER_VIRTUAL_QUEUE_LIMIT |
A resource limit on the number of samples published by a remote writer on behalf of a virtual writer that a DDS_DataReader may store was reached. This constant is an extension to the DDS standard. |
| DDS_LOST_BY_OUT_OF_MEMORY |
A sample was lost because there was not enough memory to store the sample. This constant is an extension to the DDS standard. |
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_REMOTE_WRITERS_PER_INSTANCE_LIMIT |
A resource limit on the number of remote writers for a single instance 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. |
| DDS_REJECTED_BY_VIRTUAL_WRITERS_LIMIT |
A resource limit on the number of virtual writers from which a DDS_DataReader may read was reached. This constant is an extension to the DDS standard. |
| DDS_REJECTED_BY_REMOTE_WRITERS_PER_SAMPLE_LIMIT |
A resource limit on the number of remote writers per sample was reached. This constant is an extension to the DDS standard. |
| DDS_REJECTED_BY_REMOTE_WRITER_SAMPLES_PER_VIRTUAL_QUEUE_LIMIT |
A resource limit on the number of samples published by a remote writer on behalf of a virtual writer that a DDS_DataReader may store was reached. This constant is an extension to the DDS standard. |
| 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.
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.
Important: When you loan data from the middleware, you must not keep any pointers to any part of the data samples or the DDS_SampleInfo objects after the call to FooDataReader_return_loan. Returning the loan places the objects back into a pool, allowing the middleware to overwrite them with new data.
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 and the DDS_DataReaderResourceLimitsQosPolicy.
Important: If the samples "returned" by this function are loaned from RTI Connext (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, up to the limits described in the documentation for FooDataReader_take(). |
| sample_states | <<in>> Data samples matching one of these sample_states are returned. See the valid values for this parameter here: DDS_SampleStateKind. |
| view_states | <<in>> Data samples matching one of these view_state are returned. See the valid values for this parameter here: DDS_ViewStateKind. |
| instance_states | <<in>> Data samples matching ones of these instance_state are returned. See the valid values for this parameter here: DDS_InstanceStateKind. |
| 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 matches the specified DDS_SampleStateMask, DDS_ViewStateMask and DDS_InstanceStateMask.
This operation may fail with DDS_RETCODE_ERROR if the 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:
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 insufficient 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 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 equals 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.
Important: When you loan data from the middleware, you must not keep any pointers to any part of the data samples or the DDS_SampleInfo objects after the call to FooDataReader_return_loan. Returning the loan places the objects back into a pool, allowing the middleware to overwrite them with new data.
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 and the DDS_DataReaderResourceLimitsQosPolicy.
If the sequences are not empty (maximum size not equal to 0 and length not equal to 0) when FooDataReader_take is called, samples are copied to received_data and info_seq. The application will not need to call FooDataReader_return_loan.
The order of the samples returned to the caller depends on the DDS_PresentationQosPolicy.
In any case, the relative order between the samples of one instance is consistent with the DESTINATION_ORDER policy:
source_timestamp (FIFO, smaller values of source_timestamp ahead of the larger values). 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. For an example on how take can be used, please refer to the receive example.
| 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, up to the limits described above. |
| sample_states | <<in>> Data samples matching one of these sample_states are returned. See the valid values for this parameter here: DDS_SampleStateKind. |
| view_states | <<in>> Data samples matching one of these view_state are returned. See the valid values for this parameter here: DDS_ViewStateKind. |
| instance_states | <<in>> Data samples matching one of these instance_state are returned. See the valid values for this parameter here: DDS_InstanceStateKind. |
| DDS_ReturnCode_t FooDataReader_read_w_condition | ( | FooDataReader * | self, |
| struct FooSeq * | received_data, | ||
| struct DDS_SampleInfoSeq * | info_seq, | ||
| DDS_Long | max_samples, | ||
| DDS_ReadCondition * | condition | ||
| ) |
Accesses via FooDataReader_read the samples that match the criteria specified in the DDS_ReadCondition.
This operation is especially useful in combination with DDS_QueryCondition to filter data samples based on the content.
The specified DDS_ReadCondition must be attached to the DDS_DataReader; otherwise the operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET.
In case the DDS_ReadCondition is a plain DDS_ReadCondition and not the specialized DDS_QueryCondition, the operation is equivalent to calling FooDataReader_read and passing as sample_states, view_states and instance_states the value of the corresponding attributes in the read_condition. Using this operation, the application can avoid repeating the same parameters specified when creating the DDS_ReadCondition.
The samples are accessed with the same semantics as FooDataReader_read.
If the DDS_DataReader has no samples that meet the constraints, the operation will fail with DDS_RETCODE_NO_DATA.
| 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, up to the limits described in the documentation for FooDataReader_take(). |
| condition | <<in>> the DDS_ReadCondition to select samples of interest. Cannot be NULL. |
| DDS_ReturnCode_t FooDataReader_take_w_condition | ( | FooDataReader * | self, |
| FooSeq * | received_data, | ||
| struct DDS_SampleInfoSeq * | info_seq, | ||
| DDS_Long | max_samples, | ||
| DDS_ReadCondition * | condition | ||
| ) |
Analogous to FooDataReader_read_w_condition except it accesses samples via the FooDataReader_take operation.
This operation is analogous to FooDataReader_read_w_condition except that it accesses samples via the FooDataReader_take operation.
The specified DDS_ReadCondition must be attached to the DDS_DataReader; otherwise the operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET.
The samples are accessed with the same semantics as FooDataReader_take.
This operation is especially useful in combination with DDS_QueryCondition to filter data samples based on the content.
If the DDS_DataReader has no samples that meet the constraints, the function will fail with DDS_RETCODE_NO_DATA.
| 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, up to the limits described in the documentation for FooDataReader_take(). |
| condition | <<in>> the DDS_ReadCondition to select samples of interest. Cannot be NULL. |
| 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_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 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_RETCODE_NO_DATA or DDS_RETCODE_NOT_ENABLED.
| 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, up to the limits described in the documentation for FooDataReader_take(). |
| 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, up to the limits described in the documentation for FooDataReader_take(). |
| 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_read_instance_w_condition | ( | FooDataReader * | self, |
| struct FooSeq * | received_data, | ||
| struct DDS_SampleInfoSeq * | info_seq, | ||
| DDS_Long | max_samples, | ||
| const DDS_InstanceHandle_t * | a_handle, | ||
| DDS_ReadCondition * | condition | ||
| ) |
Accesses via FooDataReader_read_instance the samples that match the criteria specified in the DDS_ReadCondition.
This operation accesses a collection of data values from the DDS_DataReader. The behavior is identical to FooDataReader_read_instance, except that all returned samples satisfy the specified condition. In other words, on success, all returned samples belong to belong the single specified instance whose handle is a_handle, and for which the specified DDS_ReadCondition evaluates to TRUE.
The behavior of the FooDataReader_read_instance_w_condition 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_w_condition operation may 'loan' elements to the output collections, which must then be returned by means of FooDataReader_return_loan.
Similar to 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.
| 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, up to the limits described in the documentation for FooDataReader_take(). |
| a_handle | <<in>> The 'next smallest' instance with a value greater than this value that has available samples will be returned. Must be a valid non-NULL DDS_InstanceHandle_t. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| condition | <<in>> the DDS_ReadCondition to select samples of interest. Cannot be NULL. |
| DDS_ReturnCode_t FooDataReader_take_instance_w_condition | ( | FooDataReader * | self, |
| struct FooSeq * | received_data, | ||
| struct DDS_SampleInfoSeq * | info_seq, | ||
| DDS_Long | max_samples, | ||
| const DDS_InstanceHandle_t * | a_handle, | ||
| DDS_ReadCondition * | condition | ||
| ) |
Accesses via FooDataReader_take_instance the samples that match the criteria specified in the DDS_ReadCondition.
This operation accesses a collection of data values from the DDS_DataReader and 'removes' them from the DDS_DataReader. The behavior is identical to FooDataReader_take_instance, except that all returned samples satisfy the specified condition. In other words, on success, all returned samples belong to belong the single specified instance whose handle is a_handle, and for which the specified DDS_ReadCondition evaluates to TRUE.
The operation has the same behavior as FooDataReader_read_instance_w_condition, except that the samples are 'taken' from the DDS_DataReader such that they are no longer accessible via subsequent 'read' or 'take' operations.
The behavior of the FooDataReader_take_instance_w_condition 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_w_condition 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.
| 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, up to the limits described in the documentation for FooDataReader_take(). |
| a_handle | <<in>> The 'next smallest' instance with a value greater than this value that has available samples will be returned. Must be a valid non-NULL DDS_InstanceHandle_t. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| condition | <<in>> the DDS_ReadCondition to select samples of interest. Cannot be NULL. |
| DDS_ReturnCode_t FooDataReader_read_next_instance | ( | FooDataReader * | self, |
| struct FooSeq * | received_data, | ||
| struct DDS_SampleInfoSeq * | info_seq, | ||
| DDS_Long | max_samples, | ||
| const DDS_InstanceHandle_t * | previous_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 where all the samples belong to a single instance. The behavior is similar to FooDataReader_read_instance, except that the actual instance is not directly specified. Rather, the samples will all belong to the 'next' instance with instance_handle 'greater' than the specified 'previous_handle' that has available samples.
This operation implies the existence of a total order 'greater-than' relationship between the instance handles. The specifics of this relationship are not all important and are implementation specific. The important thing is that, according to the middleware, all instances are ordered relative to each other. This ordering is between the instance handles; It should not depend on the state of the instance (e.g. whether it has data or not) and must be defined even for instance handles that do not correspond to instances currently managed by the DDS_DataReader. For the purposes of the ordering, it should be 'as if' each instance handle was represented as unique integer.
The behavior of FooDataReader_read_next_instance is 'as if' the DDS_DataReader invoked FooDataReader_read_instance, passing the smallest instance_handle among all the ones that: (a) are greater than previous_handle, and (b) have available samples (i.e. samples that meet the constraints imposed by the specified states).
The special value DDS_HANDLE_NIL is guaranteed to be 'less than' any valid instance_handle. So the use of the parameter value previous_handle == DDS_HANDLE_NIL will return the samples for the instance which has the smallest instance_handle among all the instances that contain available samples.
The operation FooDataReader_read_next_instance is intended to be used in an application-driven iteration, where the application starts by passing previous_handle == DDS_HANDLE_NIL, examines the samples returned, and then uses the instance_handle returned in the DDS_SampleInfo as the value of the previous_handle argument to the next call to FooDataReader_read_next_instance. The iteration continues until FooDataReader_read_next_instance fails with the value DDS_RETCODE_NO_DATA .
Note that it is possible to call the FooDataReader_read_next_instance operation with a previous_handle that does not correspond to an instance currently managed by the DDS_DataReader. This is because as stated earlier the 'greater-than' relationship is defined even for handles not managed by the DDS_DataReader. One practical situation where this may occur is when an application is iterating though all the instances, takes all the samples of a DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE instance, returns the loan (at which point the instance information may be removed, and thus the handle becomes invalid), and tries to read the next instance. The behavior of the FooDataReader_read_next_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.
| 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, up to the limits described in the documentation for FooDataReader_take(). |
| previous_handle | <<in>> The 'next smallest' instance with a value greater than this value that has available samples will be returned. Must be a valid non-NULL DDS_InstanceHandle_t. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| sample_states | <<in>> data samples matching ones of these sample_states are returned. See the valid values for this parameter here: DDS_SampleStateKind. |
| view_states | <<in>> data samples matching ones of these view_state are returned. See the valid values for this parameter here: DDS_ViewStateKind. |
| instance_states | <<in>> data samples matching ones of these instance_state are returned. See the valid values for this parameter here: DDS_InstanceStateKind. |
| DDS_ReturnCode_t FooDataReader_take_next_instance | ( | FooDataReader * | self, |
| struct FooSeq * | received_data, | ||
| struct DDS_SampleInfoSeq * | info_seq, | ||
| DDS_Long | max_samples, | ||
| const DDS_InstanceHandle_t * | previous_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 and 'removes' them from the DDS_DataReader.
This operation has the same behavior as FooDataReader_read_next_instance, except that the samples are 'taken' from the DDS_DataReader such that they are no longer accessible via subsequent 'read' or 'take' operations.
Similar to the operation FooDataReader_read_next_instance, it is possible to call FooDataReader_take_next_instance with a previous_handle that does not correspond to an instance currently managed by the DDS_DataReader.
The behavior of the FooDataReader_take_next_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_next_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.
| 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, up to the limits described in the documentation for FooDataReader_take(). |
| previous_handle | <<in>> The 'next smallest' instance with a value greater than this value that has available samples will be returned. Must be a valid non-NULL DDS_InstanceHandle_t. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| 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_read_next_instance_w_condition | ( | FooDataReader * | self, |
| struct FooSeq * | received_data, | ||
| struct DDS_SampleInfoSeq * | info_seq, | ||
| DDS_Long | max_samples, | ||
| const DDS_InstanceHandle_t * | previous_handle, | ||
| DDS_ReadCondition * | condition | ||
| ) |
Accesses via FooDataReader_read_next_instance the samples that match the criteria specified in the DDS_ReadCondition.
This operation accesses a collection of data values from the DDS_DataReader. The behavior is identical to FooDataReader_read_next_instance, except that all returned samples satisfy the specified condition. In other words, on success, all returned samples belong to the same instance, and the instance is the instance with 'smallest' instance_handle among the ones that verify: (a) instance_handle >= previous_handle, and (b) have samples for which the specified DDS_ReadCondition evaluates to TRUE.
Similar to the operation FooDataReader_read_next_instance, it is possible to call FooDataReader_read_next_instance_w_condition with a previous_handle that does not correspond to an instance currently managed by the DDS_DataReader.
The behavior of the FooDataReader_read_next_instance_w_condition 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_next_instance_w_condition 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.
| 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, up to the limits described in the documentation for FooDataReader_take(). |
| previous_handle | <<in>> The 'next smallest' instance with a value greater than this value that has available samples will be returned. Must be a valid non-NULL DDS_InstanceHandle_t. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| condition | <<in>> the DDS_ReadCondition to select samples of interest. Cannot be NULL. |
| DDS_ReturnCode_t FooDataReader_take_next_instance_w_condition | ( | FooDataReader * | self, |
| struct FooSeq * | received_data, | ||
| struct DDS_SampleInfoSeq * | info_seq, | ||
| DDS_Long | max_samples, | ||
| const DDS_InstanceHandle_t * | previous_handle, | ||
| DDS_ReadCondition * | condition | ||
| ) |
Accesses via FooDataReader_take_next_instance the samples that match the criteria specified in the DDS_ReadCondition.
This operation accesses a collection of data values from the DDS_DataReader and 'removes' them from the DDS_DataReader.
The operation has the same behavior as FooDataReader_read_next_instance_w_condition, except that the samples are 'taken' from the DDS_DataReader such that they are no longer accessible via subsequent 'read' or 'take' operations.
Similar to the operation FooDataReader_read_next_instance, it is possible to call FooDataReader_take_next_instance_w_condition with a previous_handle that does not correspond to an instance currently managed by the DDS_DataReader.
The behavior of the FooDataReader_take_next_instance_w_condition 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 FooDataReader_read, the FooDataReader_take_next_instance_w_condition 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.
| 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, up to the limits described in the documentation for FooDataReader_take(). |
| previous_handle | <<in>> The 'next smallest' instance with a value greater than this value that has available samples will be returned. Must be a valid non-NULL DDS_InstanceHandle_t. The function will fail with DDS_RETCODE_BAD_PARAMETER if it is NULL. |
| condition | <<in>> the DDS_ReadCondition to select samples of interest. Cannot be NULL. |
| 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_ReturnCode_t FooDataReader_get_key_value | ( | FooDataReader * | self, |
| Foo * | key_holder, | ||
| const DDS_InstanceHandle_t * | handle | ||
| ) |
Retrieve the instance key that corresponds to an instance handle.
Useful for keyed data types.
The operation will only fill the fields that form the key inside the key_holder instance.
For keyed data types, this operation may fail with DDS_RETCODE_BAD_PARAMETER if the handle does not correspond to an existing data-object known to the DDS_DataReader.
| self | <<in>> Cannot be NULL. |
| key_holder | <<inout>> a user data type specific key holder, whose key fields are filled by this operation. If Foo has no key, this function has no effect. This function will fail with DDS_RETCODE_BAD_PARAMETER if key_holder is NULL. |
| handle | <<in>> the instance whose key is to be retrieved. If Foo has a key, handle must represent an existing instance of type Foo known to the DDS_DataReader. Otherwise, this function will fail with DDS_RETCODE_BAD_PARAMETER. |
If Foo has a key and handle is DDS_HANDLE_NIL, this function will fail with DDS_RETCODE_BAD_PARAMETER.
If Foo has a key and handle represents an instance of another type or an instance of type Foo that has been unregistered, this function will fail with DDS_RETCODE_BAD_PARAMETER. If Foo has no key, this function has no effect.
This function will fail with DDS_RETCODE_BAD_PARAMETER if handle is NULL.
| DDS_InstanceHandle_t FooDataReader_lookup_instance | ( | FooDataReader * | self, |
| const Foo * | key_holder | ||
| ) |
Retrieves 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 DDS_HANDLE_NIL.
| DDS_ReturnCode_t DDS_RequestedDeadlineMissedStatus_initialize | ( | struct DDS_RequestedDeadlineMissedStatus * | self | ) |
Initializer for new status instances.
New DDS_RequestedDeadlineMissedStatus instances on heap should be initialized with this function before they are passed to any function. This step ensures that those contained fields that use dynamic memory are properly initialized. This function does not allocate memory.
DDS_RequestedDeadlineMissedStatus_finalize should be called to free the contained fields that use dynamic memory:
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_RequestedDeadlineMissedStatus_copy | ( | struct DDS_RequestedDeadlineMissedStatus * | self, |
| const struct DDS_RequestedDeadlineMissedStatus * | source | ||
| ) |
Copy the contents of the given status into this status.
Status instances can use dynamic memory because of the sequences contained in some status. A shallow copy by assignment is therefore unsafe. This function performs a deep-copy, allocating memory if necessary.
| DDS_ReturnCode_t DDS_RequestedDeadlineMissedStatus_finalize | ( | struct DDS_RequestedDeadlineMissedStatus * | self | ) |
Free any dynamic memory allocated by status instances.
some status may use dynamic memory (regardless of whether the status itself is in dynamic memory). This function frees that memory but otherwise leaves this status 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).
Note that if this status 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 status instance after calling this function.
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_LivelinessChangedStatus_initialize | ( | struct DDS_LivelinessChangedStatus * | self | ) |
Initializer for new status instances.
New DDS_LivelinessChangedStatus instances on heap should be initialized with this function before they are passed to any function. This step ensures that those contained fields that use dynamic memory are properly initialized. This function does not allocate memory.
DDS_LivelinessChangedStatus_finalize should be called to free the contained fields that use dynamic memory:
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_LivelinessChangedStatus_copy | ( | struct DDS_LivelinessChangedStatus * | self, |
| const struct DDS_LivelinessChangedStatus * | source | ||
| ) |
Copy the contents of the given status into this status.
Status instances can use dynamic memory because of the sequences contained in some status. A shallow copy by assignment is therefore unsafe. This function performs a deep-copy, allocating memory if necessary.
| DDS_ReturnCode_t DDS_LivelinessChangedStatus_finalize | ( | struct DDS_LivelinessChangedStatus * | self | ) |
Free any dynamic memory allocated by status instances.
some status may use dynamic memory (regardless of whether the status itself is in dynamic memory). This function frees that memory but otherwise leaves this status 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).
Note that if this status 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 status instance after calling this function.
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_RequestedIncompatibleQosStatus_initialize | ( | struct DDS_RequestedIncompatibleQosStatus * | self | ) |
Initializer for new status instances.
New DDS_RequestedIncompatibleQosStatus instances on heap should be initialized with this function before they are passed to any function. This step ensures that those contained fields that use dynamic memory are properly initialized. This function does not allocate memory.
DDS_RequestedIncompatibleQosStatus_finalize should be called to free the contained fields that use dynamic memory:
| DDS_ReturnCode_t DDS_RequestedIncompatibleQosStatus_copy | ( | struct DDS_RequestedIncompatibleQosStatus * | self, |
| const struct DDS_RequestedIncompatibleQosStatus * | source | ||
| ) |
Copy the contents of the given status into this status.
Status instances can use dynamic memory because of the sequences contained in some status. A shallow copy by assignment is therefore unsafe. This function performs a deep-copy, allocating memory if necessary.
| DDS_ReturnCode_t DDS_RequestedIncompatibleQosStatus_finalize | ( | struct DDS_RequestedIncompatibleQosStatus * | self | ) |
Free any dynamic memory allocated by status instances.
some status may use dynamic memory (regardless of whether the status itself is in dynamic memory). This function frees that memory but otherwise leaves this status 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).
Note that if this status 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 status instance after calling this function.
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_SampleLostStatus_initialize | ( | struct DDS_SampleLostStatus * | self | ) |
Initializer for new status instances.
New DDS_SampleLostStatus instances on heap should be initialized with this function before they are passed to any function. This step ensures that those contained fields that use dynamic memory are properly initialized. This function does not allocate memory.
DDS_RequestedIncompatibleQosStatus_finalize should be called to free the contained fields that use dynamic memory:
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_SampleLostStatus_copy | ( | struct DDS_SampleLostStatus * | self, |
| const struct DDS_SampleLostStatus * | source | ||
| ) |
Copy the contents of the given status into this status.
Status instances can use dynamic memory because of the sequences contained in some status. A shallow copy by assignment is therefore unsafe. This function performs a deep-copy, allocating memory if necessary.
| DDS_ReturnCode_t DDS_SampleLostStatus_finalize | ( | struct DDS_SampleLostStatus * | self | ) |
Free any dynamic memory allocated by status instances.
some status may use dynamic memory (regardless of whether the status itself is in dynamic memory). This function frees that memory but otherwise leaves this status 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).
Note that if this status 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 status instance after calling this function.
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_SampleRejectedStatus_initialize | ( | struct DDS_SampleRejectedStatus * | self | ) |
Initializer for new status instances.
New DDS_SampleRejectedStatus instances on heap should be initialized with this function before they are passed to any function. This step ensures that those contained fields that use dynamic memory are properly initialized. This function does not allocate memory.
DDS_RequestedIncompatibleQosStatus_finalize should be called to free the contained fields that use dynamic memory:
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_SampleRejectedStatus_copy | ( | struct DDS_SampleRejectedStatus * | self, |
| const struct DDS_SampleRejectedStatus * | source | ||
| ) |
Copy the contents of the given status into this status.
Status instances can use dynamic memory because of the sequences contained in some status. A shallow copy by assignment is therefore unsafe. This function performs a deep-copy, allocating memory if necessary.
| DDS_ReturnCode_t DDS_SampleRejectedStatus_finalize | ( | struct DDS_SampleRejectedStatus * | self | ) |
Free any dynamic memory allocated by status instances.
some status may use dynamic memory (regardless of whether the status itself is in dynamic memory). This function frees that memory but otherwise leaves this status 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).
Note that if this status 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 status instance after calling this function.
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_SubscriptionMatchedStatus_initialize | ( | struct DDS_SubscriptionMatchedStatus * | self | ) |
Initializer for new status instances.
New DDS_SubscriptionMatchedStatus instances on heap should be initialized with this function before they are passed to any function. This step ensures that those contained fields that use dynamic memory are properly initialized. This function does not allocate memory.
DDS_RequestedIncompatibleQosStatus_finalize should be called to free the contained fields that use dynamic memory:
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_SubscriptionMatchedStatus_copy | ( | struct DDS_SubscriptionMatchedStatus * | self, |
| const struct DDS_SubscriptionMatchedStatus * | source | ||
| ) |
Copy the contents of the given status into this status.
Status instances can use dynamic memory because of the sequences contained in some status. A shallow copy by assignment is therefore unsafe. This function performs a deep-copy, allocating memory if necessary.
| DDS_ReturnCode_t DDS_SubscriptionMatchedStatus_finalize | ( | struct DDS_SubscriptionMatchedStatus * | self | ) |
Free any dynamic memory allocated by status instances.
some status may use dynamic memory (regardless of whether the status itself is in dynamic memory). This function frees that memory but otherwise leaves this status 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).
Note that if this status 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 status instance after calling this function.
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_DataReaderCacheStatus_initialize | ( | struct DDS_DataReaderCacheStatus * | self | ) |
Initializer for new status instances.
New DDS_DataReaderCacheStatus instance on heap should be initialized with this function before they are passed to any function. This step ensures that those contained fields that use dynamic memory are properly initialized. This function does not allocate memory.
DDS_DataReaderCacheStatus_finalize should be called to free the contained fields that use dynamic memory:
| DDS_ReturnCode_t DDS_DataReaderCacheStatus_copy | ( | struct DDS_DataReaderCacheStatus * | self, |
| const struct DDS_DataReaderCacheStatus * | source | ||
| ) |
Copy the contents of the given status into this status.
Status instances can use dynamic memory because of the sequences contained in some status. A shallow copy by assignment is therefore unsafe. This function performs a deep-copy, allocating memory if necessary.
| DDS_ReturnCode_t DDS_DataReaderCacheStatus_finalize | ( | struct DDS_DataReaderCacheStatus * | self | ) |
Free any dynamic memory allocated by status instances.
some status may use dynamic memory (regardless of whether the status itself is in dynamic memory). This function frees that memory but otherwise leaves this status 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).
Note that if this status 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 status instance after calling this function.
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_DataReaderProtocolStatus_initialize | ( | struct DDS_DataReaderProtocolStatus * | self | ) |
Initializer for new status instances.
New DDS_DataReaderProtocolStatus instance on heap should be initialized with this function before they are passed to any function. This step ensures that those contained fields that use dynamic memory are properly initialized. This function does not allocate memory.
DDS_DataReaderProtocolStatus_finalize should be called to free the contained fields that use dynamic memory:
| DDS_ReturnCode_t DDS_DataReaderProtocolStatus_copy | ( | struct DDS_DataReaderProtocolStatus * | self, |
| const struct DDS_DataReaderProtocolStatus * | source | ||
| ) |
Copy the contents of the given status into this status.
Status instances can use dynamic memory because of the sequences contained in some status. A shallow copy by assignment is therefore unsafe. This function performs a deep-copy, allocating memory if necessary.
| DDS_ReturnCode_t DDS_DataReaderProtocolStatus_finalize | ( | struct DDS_DataReaderProtocolStatus * | self | ) |
Free any dynamic memory allocated by status instances.
some status may use dynamic memory (regardless of whether the status itself is in dynamic memory). This function frees that memory but otherwise leaves this status 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).
Note that if this status 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 status instance after calling this function.
| self | <<in>> Cannot be NULL. |
| DDS_Boolean DDS_DataReaderQos_equals | ( | const struct DDS_DataReaderQos * | self, |
| const struct DDS_DataReaderQos * | other | ||
| ) |
Compares two DDS_DataReaderQos for equality.
| self | <<in>> This DataReaderQos. |
| other | <<in>> The other DataReaderQos to be compared with this DataReaderQos. |
| DDS_ReturnCode_t DDS_DataReaderQos_initialize | ( | struct DDS_DataReaderQos * | self | ) |
Initializer for new QoS instances.
New DDS_DataReaderQos instances on 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.
Calling this function is not a substitute for calling DDS_DataReader_get_qos or DDS_DomainParticipant_get_default_datareader_qos; one of those should be called subsequently to setting the QoS of any new or existing entity. DDS_DataReaderQos_finalize should be called to free the contained QoS policies that use dynamic 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 | ) |
Accesses the DDS_DataReader's supertype instance.
| dataReader | <<in>> Cannot be NULL. |
| DDS_ReadCondition* DDS_DataReader_create_readcondition | ( | DDS_DataReader * | self, |
| DDS_SampleStateMask | sample_states, | ||
| DDS_ViewStateMask | view_states, | ||
| DDS_InstanceStateMask | instance_states | ||
| ) |
Creates a DDS_ReadCondition.
The returned DDS_ReadCondition will be attached and belong to the DDS_DataReader.
| self | <<in>> Cannot be NULL. |
| sample_states | <<in>> sample state of the data samples that are of interest |
| view_states | <<in>> view state of the data samples that are of interest |
| instance_states | <<in>> instance state of the data samples that are of interest |
| DDS_QueryCondition* DDS_DataReader_create_querycondition | ( | DDS_DataReader * | self, |
| DDS_SampleStateMask | sample_states, | ||
| DDS_ViewStateMask | view_states, | ||
| DDS_InstanceStateMask | instance_states, | ||
| const char * | query_expression, | ||
| const struct DDS_StringSeq * | query_parameters | ||
| ) |
Creates a DDS_QueryCondition.
The returned DDS_QueryCondition will be attached and belong to the DDS_DataReader.
Queries and Filters Syntax describes the syntax of query_expression and query_parameters.
| self | <<in>> Cannot be NULL. |
| sample_states | <<in>> sample state of the data samples that are of interest |
| view_states | <<in>> view state of the data samples that are of interest |
| instance_states | <<in>> instance state of the data samples that are of interest |
| query_expression | <<in>> Expression for the query. Cannot be NULL. |
| query_parameters | <<in>> Parameters for the query expression. Cannot be NULL. |
| DDS_ReturnCode_t DDS_DataReader_delete_readcondition | ( | DDS_DataReader * | self, |
| DDS_ReadCondition * | condition | ||
| ) |
Deletes a DDS_ReadCondition or DDS_QueryCondition attached to the DDS_DataReader.
Since DDS_QueryCondition specializes DDS_ReadCondition, it can also be used to delete a DDS_QueryCondition.
| DDS_ReturnCode_t DDS_DataReader_delete_contained_entities | ( | DDS_DataReader * | self | ) |
Deletes all the entities that were created by means of the "create" operations on the DDS_DataReader.
Deletes all contained DDS_ReadCondition and DDS_QueryCondition objects.
The operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET if the any of the contained entities is in a state where it cannot be deleted.
Once DDS_DataReader_delete_contained_entities completes successfully, the application may delete the DDS_DataReader, knowing that it has no contained DDS_ReadCondition and DDS_QueryCondition objects.
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_DataReader_wait_for_historical_data | ( | DDS_DataReader * | self, |
| const struct DDS_Duration_t * | max_wait | ||
| ) |
Waits until all "historical" data is received for DDS_DataReader entities that have a non-VOLATILE Durability Qos kind.
This operation is intended only for DDS_DataReader entities that have a non-VOLATILE Durability QoS kind.
As soon as an application enables a non-VOLATILE DDS_DataReader, it will start receiving both "historical" data (i.e., the data that was written prior to the time the DDS_DataReader joined the domain) as well as any new data written by the DDS_DataWriter entities. There are situations where the application logic may require the application to wait until all "historical" data is received. This is the purpose of the DDS_DataReader_wait_for_historical_data operations.
DDS_DataReader_wait_for_historical_data() blocks the calling thread until either all "historical" data is received, or until the duration specified by the max_wait parameter elapses, whichever happens first. It will return immediately if no DataWriters have been discovered at the time the operation is called; therefore it is advisable to make sure at least one DDS_DataWriter has been discovered before calling this operation. (One way to do this is by using DDS_DataReader_get_subscription_matched_status.)
A successful completion indicates that all the "historical" data was "received"; timing out indicates that max_wait elapsed before all the data was received.
| DDS_ReturnCode_t DDS_DataReader_acknowledge_sample_w_response | ( | DDS_DataReader * | self, |
| const struct DDS_SampleInfo * | sample_info, | ||
| const struct DDS_AckResponseData_t * | response_data | ||
| ) |
Acknowledge a single sample explicitly.
Applicable only when DDS_ReliabilityQosPolicy::acknowledgment_kind = DDS_APPLICATION_EXPLICIT_ACKNOWLEDGMENT_MODE
A call to this function does not necessarily trigger the sending of an AppAck RTPS message from the DataReader to the DataWriter. How and when AppAck messages are sent can be configured using the QoS values DDS_RtpsReliableReaderProtocol_t::samples_per_app_ack and DDS_RtpsReliableReaderProtocol_t::app_ack_period.
The maximum length of the response is configured using DDS_DataReaderResourceLimitsQosPolicy::max_app_ack_response_length
| self | <<in>> Cannot be NULL. |
| sample_info | <<in>> DDS_SampleInfo identifying the sample being acknowledged. |
| response_data | <<in>> Response data sent to DDS_DataWriter upon acknowledgment (via DDS_DataWriterListener::on_application_acknowledgment) |
| DDS_ReturnCode_t DDS_DataReader_acknowledge_all_w_response | ( | DDS_DataReader * | self, |
| const struct DDS_AckResponseData_t * | response_data | ||
| ) |
Acknowledge all previously accessed samples.
Applicable only when DDS_ReliabilityQosPolicy::acknowledgment_kind = DDS_APPLICATION_EXPLICIT_ACKNOWLEDGMENT_MODE
A call to this function does not necessarily trigger the sending of an AppAck RTPS message from the DataReader to the DataWriter. How and when AppAck messages are sent can be configured using the QoS values DDS_RtpsReliableReaderProtocol_t::samples_per_app_ack and DDS_RtpsReliableReaderProtocol_t::app_ack_period.
The maximum length of the response is configured using DDS_DataReaderResourceLimitsQosPolicy::max_app_ack_response_length
| self | <<in>> Cannot be NULL. |
| response_data | <<in>> Response data sent to DDS_DataWriter upon acknowledgment |
| DDS_ReturnCode_t DDS_DataReader_acknowledge_sample | ( | DDS_DataReader * | self, |
| const struct DDS_SampleInfo * | sample_info | ||
| ) |
Acknowledge a single sample explicitly.
Applicable only when DDS_ReliabilityQosPolicy::acknowledgment_kind = DDS_APPLICATION_EXPLICIT_ACKNOWLEDGMENT_MODE
A call to this function does not necessarily trigger the sending of an AppAck RTPS message from the DataReader to the DataWriter. How and when AppAck messages are sent can be configured using the QoS values DDS_RtpsReliableReaderProtocol_t::samples_per_app_ack and DDS_RtpsReliableReaderProtocol_t::app_ack_period.
| self | <<in>> Cannot be NULL. |
| sample_info | <<in>> DDS_SampleInfo identifying the sample being acknowledged. |
| DDS_ReturnCode_t DDS_DataReader_acknowledge_all | ( | DDS_DataReader * | self | ) |
Acknowledge all previously accessed samples.
Applicable only when DDS_ReliabilityQosPolicy::acknowledgment_kind = DDS_APPLICATION_EXPLICIT_ACKNOWLEDGMENT_MODE
A call to this function does not necessarily trigger the sending of an AppAck RTPS message from the DataReader to the DataWriter. How and when AppAck messages are sent can be configured using the QoS values DDS_RtpsReliableReaderProtocol_t::samples_per_app_ack and DDS_RtpsReliableReaderProtocol_t::app_ack_period.
| 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, compatible QoS common partition that the DDS_DomainParticipant has not indicated should be "ignored" by means of the DDS_DomainParticipant_ignore_publication operation.
The handles returned in the publication_handles list are the ones that are used by the RTI Connext 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.
Matched publications are those with a matching DDS_Topic, compatible QoS and common partition that the application has not indicated should be "ignored" by means of the DDS_DomainParticipant_ignore_publication operation.
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.
Note: This operation does not retrieve the following information in DDS_PublicationBuiltinTopicData:
The above information is available through DDS_DataReaderListener::on_data_available() (if a reader listener is installed on the DDS_PublicationBuiltinTopicDataDataReader).
| 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_ReturnCode_t DDS_DataReader_get_matched_publication_participant_data | ( | DDS_DataReader * | self, |
| struct DDS_ParticipantBuiltinTopicData * | participant_data, | ||
| const DDS_InstanceHandle_t * | publication_handle | ||
| ) |
<<extension>> This operation retrieves the information on the discovered DDS_DomainParticipant associated with the publication that is currently matching with the DDS_DataReader.
Matched Participants are those with a matching DDS_Topic, compatible QoS and common partition that the application has not indicated should be "ignored" by means of the DDS_DomainParticipant_ignore_publication operation.
The publication_handle must correspond to a publication currently associated with the DDS_DataReader. Otherwise, the operation will fail with DDS_RETCODE_BAD_PARAMETER. The operation may also fail with DDS_RETCODE_PRECONDITION_NOT_MET if the publication corresponds to the same DDS_DomainParticipant that the DataReader belongs to. Use the operation DDS_DataReader_get_matched_publications to find the publications that are currently matched with the DDS_DataReader.
Note: This operation does not retrieve the DDS_ParticipantBuiltinTopicData::property.
The above information is available through DDS_DataReaderListener::on_data_available() (if a reader listener is installed on the DDS_PublicationBuiltinTopicDataDataReader).
| self | <<in>> Cannot be NULL. |
| participant_data | <<inout>>. The information to be filled in on the associated participant. Cannot be NULL. |
| publication_handle | <<in>>. Handle to a specific publication associated with a 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 | ) |
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 | ) |
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 | ||
| ) |
Accesses the DDS_SAMPLE_REJECTED_STATUS communication status.
This also resets the status so that it is no longer considered changed.
| 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 | ||
| ) |
Accesses the DDS_LIVELINESS_CHANGED_STATUS communication status.
This also resets the status so that it is no longer considered changed.
| 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 | ||
| ) |
Accesses the DDS_REQUESTED_DEADLINE_MISSED_STATUS communication status.
This also resets the status so that it is no longer considered changed.
| self | <<in>> Cannot be NULL. |
| status | <<inout>> DDS_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 | ||
| ) |
Accesses the DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS communication status.
This also resets the status so that it is no longer considered changed.
| self | <<in>> Cannot be NULL. |
| status | <<inout>> DDS_RequestedIncompatibleQosStatus to be filled in. Cannot be NULL. |
| DDS_ReturnCode_t DDS_DataReader_get_subscription_matched_status | ( | DDS_DataReader * | self, |
| struct DDS_SubscriptionMatchedStatus * | status | ||
| ) |
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 | ||
| ) |
Accesses the DDS_SAMPLE_LOST_STATUS communication status.
This also resets the status so that it is no longer considered changed.
| self | <<in>> Cannot be NULL. |
| status | <<inout>> DDS_SampleLostStatus to be filled in. Cannot be NULL. |
| DDS_ReturnCode_t DDS_DataReader_get_datareader_cache_status | ( | DDS_DataReader * | self, |
| struct DDS_DataReaderCacheStatus * | status | ||
| ) |
<<extension>> Get the datareader cache status for this reader.
| self | <<in>> Cannot be NULL. |
| status | <<inout>> DDS_DataReaderCacheStatus to be filled in. Cannot be NULL. |
| DDS_ReturnCode_t DDS_DataReader_get_datareader_protocol_status | ( | DDS_DataReader * | self, |
| struct DDS_DataReaderProtocolStatus * | status | ||
| ) |
<<extension>> Get the datareader protocol status for this reader.
This also resets the status so that it is no longer considered changed.
| self | <<in>> Cannot be NULL. |
| status | <<inout>> DDS_DataReaderProtocolStatus to be filled in. Cannot be NULL. |
| DDS_ReturnCode_t DDS_DataReader_get_matched_publication_datareader_protocol_status | ( | DDS_DataReader * | self, |
| struct DDS_DataReaderProtocolStatus * | status, | ||
| const DDS_InstanceHandle_t * | publication_handle | ||
| ) |
<<extension>> Get the datareader protocol status for this reader, per matched publication identified by the publication_handle.
This also resets the status so that it is no longer considered changed.
Note: Status for a remote entity is only kept while the entity is alive. Once a remote entity is no longer alive, its status is deleted.
| self | <<in>> Cannot be NULL. |
| status | <<inout>>. 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_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::user_data, DDS_DataReaderQos::deadline, DDS_DataReaderQos::latency_budget, DDS_DataReaderQos::time_based_filter, DDS_DataReaderQos::reader_data_lifecycle 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. Immutable 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_set_qos_with_profile | ( | DDS_DataReader * | self, |
| const char * | library_name, | ||
| const char * | profile_name | ||
| ) |
<<extension>> Change the QoS of this reader using the input XML QoS profile.
This operation modifies the QoS of the DDS_DataReader.
The DDS_DataReaderQos::user_data, DDS_DataReaderQos::deadline, DDS_DataReaderQos::latency_budget, DDS_DataReaderQos::time_based_filter, DDS_DataReaderQos::reader_data_lifecycle can be changed. The other policies are immutable.
| self | <<in>> Cannot be NULL. |
| library_name | <<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDS_Subscriber_set_default_library). |
| profile_name | <<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDS_Subscriber_set_default_profile). |
| 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_get_listenerX | ( | DDS_DataReader * | self, |
| struct DDS_DataReaderListener * | listener | ||
| ) |
<<extension>> Get the reader listener.
An alternative form of get_listener that fills in an existing listener structure rather than returning one on the stack.
| self | <<in>> Cannot be NULL. |
| listener | <<inout>> DDS_DataReaderListener structure to be filled up. Cannot be NULL. |
RTI Connext C API Version 5.2.3
Copyright © Wed Apr 27 2016
Real-Time Innovations, Inc