CoreDX DDS C# Reference Manual
|
Inherits DataReaderI< T >.
Public Member Functions | |
| ReturnCode_t | get_key_value (Foo key_holder, InstanceHandle_t handle) |
| InstanceHandle_t | lookup_instance (Foo instance_data) |
| ReturnCode_t | return_loan (List< Foo > received_data, List< SampleInfo > sample_infos) |
| ReturnCode_t | read (List< Foo > received_data, List< SampleInfo > sample_infos, int max_samples, uint sample_states, uint view_states, uint instance_states) |
| ReturnCode_t | take (List< Foo > received_data, List< SampleInfo > sample_infos, int max_samples, uint sample_states, uint view_states, uint instance_states) |
| ReturnCode_t | read_w_condition (List< Foo > received_data, List< SampleInfo > sample_infos, int max_samples, ReadCondition condition) |
| ReturnCode_t | take_w_condition (List< Foo > received_data, List< SampleInfo > sample_infos, int max_samples, ReadCondition condition) |
| ReturnCode_t | read_next_sample (Foo received_data, SampleInfo sample_info) |
| ReturnCode_t | take_next_sample (Foo received_data, SampleInfo sample_info) |
| ReturnCode_t | read_instance (List< Foo > received_data, List< SampleInfo > sample_infos, int max_samples, InstanceHandle_t handle, uint sample_states, uint view_states, uint instance_states) |
| ReturnCode_t | take_instance (List< Foo > received_data, List< SampleInfo > sample_infos, int max_samples, InstanceHandle_t handle, uint sample_states, uint view_states, uint instance_states) |
| ReturnCode_t | read_next_instance (List< Foo > received_data, List< SampleInfo > sample_infos, int max_samples, InstanceHandle_t prev_handle, uint sample_states, uint view_states, uint instance_states) |
| ReturnCode_t | take_next_instance (List< Foo > received_data, List< SampleInfo > sample_infos, int max_samples, InstanceHandle_t prev_handle, uint sample_states, uint view_states, uint instance_states) |
| ReturnCode_t | read_next_instance_w_condition (List< Foo > received_data, List< SampleInfo > sample_infos, int max_samples, InstanceHandle_t handle, ReadCondition condition) |
| ReturnCode_t | take_next_instance_w_condition (List< Foo > received_data, List< SampleInfo > sample_infos, int max_samples, InstanceHandle_t handle, ReadCondition condition) |
The FooDataReader is an example specialized DataReader (generated by the coredx_ddl compiler) for reading data samples of type 'Foo'.
The FooDataReader is an implementation of the base DataReader class that has been extended to support the 'Foo' data type.
Note: the FooDataReader is included here for documentation purposes only, and does not really exist in the com.toc.coredx.DDS package.
| ReturnCode_t get_key_value | ( | Foo | key_holder, |
| InstanceHandle_t | handle | ||
| ) |
This routine will populate the data structure indicated by key_holder with the key infomation identified by handle.
This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.
| InstanceHandle_t lookup_instance | ( | Foo | instance_data | ) |
Returns the handle that identifies the data instance provided in instance_data. The 'key' field values of the data are associated with a unique handle.
This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.
| ReturnCode_t read | ( | List< Foo > | received_data, |
| List< SampleInfo > | sample_infos, | ||
| int | max_samples, | ||
| uint | sample_states, | ||
| uint | view_states, | ||
| uint | instance_states | ||
| ) |
This operation accesses a collection of data values (with associated SampleInfo) within the DataReader. This routine, and the related take(), provide the interface for an application to access published data. There are several varieties of read() and take(), to facilitate different access patterns or approaches.
The primary difference between read() and take() is that take() removes all returned data samples from the DataReader while read() does not. Sequential read() calls will return the same data samples each time (if nothing else changes); while sequential take() calls will return data samples for only the first call. Subsequent take() calls will return an empty collection (if no new data arrives).
The specific behavior of read() depends on several things: input paramters, the QoS settings of the DataReader, and the state of recieved data. First, the received_data and sample_infos arguments affect the following:
The argument max_samples is used to further limit the number of samples returned.
The sample_states, view_states, and instance_states arguments are used to selectively add data samples to the returned collections. These arguments indicate the desired 'states' for data samples and instances. These state arguments are bit masks; they can be the bit-wise OR of several individual state flags or they may use the special 'ANY' constants (e.g.: DDS.ANY_SAMPLE_STATE). Only samples that have a matching state for all three categories are added to the returned collection.
The order of samples in the returned collections is determined by the PRESENTATION and DESTINATION_ORDER QoS policies.
The returned collection is held in recieved_data and samples_infos. These two sequences operate together to represent a sequence of pairs (data, SampleInfo). Each data item in received_data has a corresponding entry in sample_infos that provides associated 'meta-data'. See SampleInfo for a description of this meta-data.
In CoreDX DDS, the returned sequences contain 'loaned' data. This provides zero-copy access to the data, and provides a very efficient data access mechanism. Becuase the data is 'loaned' to the application, the application is required to indicate when it is finished accessing the data. This is accomplished by calling return_loan().
The read() operation will set the SampleInfo.sample_state to DDS.READ_SAMPLE_STATE.
The read() operation may set the SampleInfo.view_state to DDS.NOT_NEW_VIEW_STATE, if a sample of the most recent generation of the instance is read.
If there is no data found, then the read() will return RETCODE_NO_DATA.
This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.
| ReturnCode_t read_instance | ( | List< Foo > | received_data, |
| List< SampleInfo > | sample_infos, | ||
| int | max_samples, | ||
| InstanceHandle_t | handle, | ||
| uint | sample_states, | ||
| uint | view_states, | ||
| uint | instance_states | ||
| ) |
This operation accesses a collection of data values (with associated SampleInfo), belonging to a particular instance, within the DataReader.
This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.
| ReturnCode_t read_next_instance | ( | List< Foo > | received_data, |
| List< SampleInfo > | sample_infos, | ||
| int | max_samples, | ||
| InstanceHandle_t | prev_handle, | ||
| uint | sample_states, | ||
| uint | view_states, | ||
| uint | instance_states | ||
| ) |
This operation accesses a collection of data values (with associated SampleInfo), instance by instance, within the DataReader. To start,pass HANDLE_NIL for parameter prev_handle. After the last instance (in order) has been taken, this routine will return RETCODE_NO_DATA.
This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.
| ReturnCode_t read_next_instance_w_condition | ( | List< Foo > | received_data, |
| List< SampleInfo > | sample_infos, | ||
| int | max_samples, | ||
| InstanceHandle_t | handle, | ||
| ReadCondition | condition | ||
| ) |
This operation accesses a collection of data values (with associated SampleInfo), instance by instance subject to a filter, within the DataReader.
This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.
| ReturnCode_t read_next_sample | ( | Foo | received_data, |
| SampleInfo | sample_info | ||
| ) |
This operation accesses a data value (with associated SampleInfo) within the DataReader.
This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.
| ReturnCode_t read_w_condition | ( | List< Foo > | received_data, |
| List< SampleInfo > | sample_infos, | ||
| int | max_samples, | ||
| ReadCondition | condition | ||
| ) |
This operation accesses a collection of data values (with associated SampleInfo), subject to a filter, within the DataReader.
This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.
| ReturnCode_t return_loan | ( | List< Foo > | received_data, |
| List< SampleInfo > | sample_infos | ||
| ) |
Returns data and sample_info values to a DataReader. When an application calls DataReader read() or take() operations, these routines 'loan' data and SampleInfo values to the application. [This is an optimization that avoids extra copies of data.] The appliction must return this 'loaned' data to the DataReader. The return_loan() routine indicates to the DataReader that the application no longer requires access to the data and sample_infos.
A call to return_loan() operation must be made only if previous read() or take() calls 'loaned' data to the application. See read() for a discussion of when data is 'loaned'.
If the received_data or sample_infos parameters provided do not identify data obtained from DataReader dr, then the error RETCODE_PRECONDITION_NOT_MET will be returned.
A DataReader cannot be deleted if any 'loans' are outstanding.
| ReturnCode_t take | ( | List< Foo > | received_data, |
| List< SampleInfo > | sample_infos, | ||
| int | max_samples, | ||
| uint | sample_states, | ||
| uint | view_states, | ||
| uint | instance_states | ||
| ) |
This operation takes a collection of data values (with associated SampleInfo) from the DataReader. This routine, and the related read(), provide the interface for an application to access published data. There are several varieties of read() and take(), to facilitate different access patterns or approaches.
The primary difference between read() and take() is that take() removes all returned data samples from the DataReader while read() does not. Sequential read() calls will return the same data samples each time (if nothing else changes); while sequential take() calls will return data samples for only the first call. Subsequent take() calls will return an empty collection (if no new data arrives).
The specific behavior of take() depends on several things: input paramters, the QoS settings of the DataReader, and the state of recieved data. First, the received_data and sample_infos arguments affect the following:
The argument max_samples is used to further limit the number of samples returned.
The sample_states, view_states, and instance_states arguments are used to selectively add data samples to the returned collections. These arguments indicate the desired 'states' for data samples and instances. These state arguments are bit masks; they can be the bit-wise OR of several individual state flags or they may use the special 'ANY' constants (e.g.: DDS.ANY_SAMPLE_STATE). Only samples that have a matching state for all three categories are added to the returned collection.
The order of samples in the returned collections is determined by the PRESENTATION and DESTINATION_ORDER QoS policies.
The returned collection is held in recieved_data and samples_infos. These two sequences operate together to represent a sequence of pairs (data, SampleInfo). Each data item in received_data has a corresponding entry in sample_infos that provides associated 'meta-data'. See SampleInfo for a description of this meta-data.
In CoreDX DDS, the returned sequences contain 'loaned' data. This provides zero-copy access to the data, and provides a very efficient data access mechanism. Becuase the data is 'loaned' to the application, the application is required to indicate when it is finished accessing the data. This is accomplished by calling return_loan().
The take() operation will set the SampleInfo.sample_state to DDS.READ_SAMPLE_STATE.
The take() operation may set the SampleInfo.view_state to DDS.NOT_NEW_VIEW_STATE, if a sample of the most recent generation of the instance is taken.
If there is no data found, then the take() will return RETCODE_NO_DATA.
This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.
| ReturnCode_t take_instance | ( | List< Foo > | received_data, |
| List< SampleInfo > | sample_infos, | ||
| int | max_samples, | ||
| InstanceHandle_t | handle, | ||
| uint | sample_states, | ||
| uint | view_states, | ||
| uint | instance_states | ||
| ) |
This operation takes a collection of data values (with associated SampleInfo), belonging to a particular instance, from the DataReader.
This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.
| ReturnCode_t take_next_instance | ( | List< Foo > | received_data, |
| List< SampleInfo > | sample_infos, | ||
| int | max_samples, | ||
| InstanceHandle_t | prev_handle, | ||
| uint | sample_states, | ||
| uint | view_states, | ||
| uint | instance_states | ||
| ) |
This operation takes a collection of data values (with associated SampleInfo), instance by instance, from the DataReader. To start,pass HANDLE_NIL for parameter prev_handle. After the last instance (in order) has been taken, this routine will return RETCODE_NO_DATA.
This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.
| ReturnCode_t take_next_instance_w_condition | ( | List< Foo > | received_data, |
| List< SampleInfo > | sample_infos, | ||
| int | max_samples, | ||
| InstanceHandle_t | handle, | ||
| ReadCondition | condition | ||
| ) |
This operation takes a collection of data values (with associated SampleInfo), instance by instance subject to a filter, from the DataReader.
This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.
| ReturnCode_t take_next_sample | ( | Foo | received_data, |
| SampleInfo | sample_info | ||
| ) |
This operation takes a data value (with associated SampleInfo) from the DataReader.
This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.
| ReturnCode_t take_w_condition | ( | List< Foo > | received_data, |
| List< SampleInfo > | sample_infos, | ||
| int | max_samples, | ||
| ReadCondition | condition | ||
| ) |
This operation takes a collection of data values (with associated SampleInfo), subject to a filter, from the DataReader.
This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.
