#ifndef OMG_DDS_SUB_FIND_HPP_ #define OMG_DDS_SUB_FIND_HPP_ /* Copyright 2010, Object Management Group, Inc. * Copyright 2010, PrismTech, Corp. * Copyright 2010, Real-Time Innovations, Inc. * All rights reserved. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ #include #include namespace dds { namespace sub { /** * This operation returns the built-in Subscriber associated with the given * given DomainParticipant. * * Each DomainParticipant contains several built-in * Topic objects. The built-in Subscriber contains the corresponding DataReader * objects to access them. All these DataReader objects belong to a single built-in * Subscriber. Note that there is exactly one built-in Subscriber associated with * each DomainParticipant. * * See @ref DCPS_Builtin_Topics "Builtin Topics" for more information. * * @param dp the domain participant * @return the built-in Subscriber */ const dds::sub::Subscriber OMG_DDS_API builtin_subscriber(const dds::domain::DomainParticipant& dp); /** * This function retrieves a previously-created DataReader * belonging to the Subscriber that is attached to a Topic with a * matching topic_name. If no such DataReader exists, the operation * will return an empty container. * * The use of this * operation on the built-in Subscriber allows access to the * built-in DataReader entities for the built-in topics * (see @ref DCPS_Builtin_Topics "Builtin Topics"). * * @param sub the Subscriber for which to find a DataReader * @param topic_name the topic name to find * @param begin a forward iterator pointing to the start of a * container in which to put the DataReaders * @param max_size the number of DataReaders to return * @return the total number of elements returned. Notice that * at most max_size will be copied using the provided iterator * */ template uint32_t find(const dds::sub::Subscriber& sub, const std::string &topic_name, FwdIterator begin, uint32_t max_size); /** * This function retrieves a previously-created DataReader * belonging to the Subscriber that is attached to a Topic with a * matching topic_name. If no such DataReader exists, the operation * will return an empty container. * * The use of this * operation on the built-in Subscriber allows access to the * built-in DataReader entities for the built-in topics * (see @ref DCPS_Builtin_Topics "Builtin Topics"). * * @param sub the Subscriber for which to find a DataReader * @param topic_name the topic name to find * @param begin a back inserting iterator pointing to the start of a * container in which to put the DataReaders * @return the total number of elements returned */ template uint32_t find(const dds::sub::Subscriber& sub, const std::string &topic_name, BinIterator begin); /** * This function retrieves a previously-created DataReader * belonging to the Subscriber that is attached to a Topic with a * matching topic_name. If no such DataReader exists, the operation * will return an empty container. * * The use of this * operation on the built-in Subscriber allows access to the * built-in DataReader entities for the built-in topics * (see @ref DCPS_Builtin_Topics "Builtin Topics"). * * @param sub the Subscriber for which to find a DataReader * @param topic_description the topic description to find * @param begin a forward iterator pointing to the start of a * container in which to put the DataReaders * @param max_size the number of DataReaders to return * @return the total number of elements returned. Notice that * at most max_size will be copied using the provided iterator */ template uint32_t find(const dds::sub::Subscriber& sub, const dds::topic::TopicDescription& topic_description, FwdIterator begin, uint32_t max_size); /** * This function retrieves a previously-created DataReader * belonging to the Subscriber that is attached to a Topic with a * matching topic_name. If no such DataReader exists, the operation * will return an empty container. * * The use of this * operation on the built-in Subscriber allows access to the * built-in DataReader entities for the built-in topics * (see @ref DCPS_Builtin_Topics "Builtin Topics"). * * @param sub the Subscriber for which to find a DataReader * @param topic_description the topic description to find * @param begin a back inserting iterator pointing to the start of a * container in which to put the DataReaders * @return the total number of elements returned */ template uint32_t find(const dds::sub::Subscriber& sub, const dds::topic::TopicDescription& topic_description, BinIterator begin); /** * This operation allows the application to access the DataReader objects that contain * samples with the specified sample_states, view_states, and * instance_states. * * If the Presentation QosPolicy of the Subscriber to which the DataReader * belongs has the access_scope set to ‘GROUP’, this operation should only be * invoked inside a begin_access/end_access block. Otherwise it will throw * error PreconditionNotMetError. * * Depending on the setting of the dds::core::policy::Presentation QoSPolicy, * the returned collection of DataReader objects may be: * - a ‘set’ containing each DataReader at most once in no specified order, * - a ‘list’ containing each DataReader one or more times in a specific order. * * This difference is due to the fact that, in the second situation it is required to access * samples belonging to different DataReader objects in a particular order. In this case, * the application should process each DataReader in the same order it appears in the * ‘list’ and read or take exactly one sample from each DataReader. The patterns that * an application should use to access data is fully described in dds::core::policy::Presentation. * * @param sub the Subscriber for which to find a DataReader * @param data_state the data_state to find * @param begin a forward iterator pointing to the start of a * container in which to put the DataReaders * @param max_size the number of DataReaders to return * @return the total number of elements returned. Notice that * at most max_size will be copied using the provided iterator */ template uint32_t find(const dds::sub::Subscriber& sub, const dds::sub::status::DataState& data_state, FwdIterator begin, uint32_t max_size); /** * This operation allows the application to access the DataReader objects that contain * samples with the specified sample_states, view_states, and * instance_states. * * If the Presentation QosPolicy of the Subscriber to which the DataReader * belongs has the access_scope set to ‘GROUP’, this operation should only be * invoked inside a begin_access/end_access block. Otherwise it will throw * error PreconditionNotMetError. * * Depending on the setting of the dds::core::policy::Presentation QoSPolicy, * the returned collection of DataReader objects may be: * - a ‘set’ containing each DataReader at most once in no specified order, * - a ‘list’ containing each DataReader one or more times in a specific order. * * This difference is due to the fact that, in the second situation it is required to access * samples belonging to different DataReader objects in a particular order. In this case, * the application should process each DataReader in the same order it appears in the * ‘list’ and read or take exactly one sample from each DataReader. The patterns that * an application should use to access data is fully described in dds::core::policy::Presentation. * * @param sub the Subscriber for which to find a DataReader * @param rs the data_state to find * @param begin a back inserting iterator pointing to the start * of a container in which to put the DataReaders * @return the total number of elements returned */ template uint32_t find(const dds::sub::Subscriber& sub, const dds::sub::status::DataState& rs, BinIterator begin); } } #endif /* OMG_DDS_SUB_FIND_HPP_ */