2 Copyright (C) 2012 Intel Corporation
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Lesser General Public
6 License as published by the Free Software Foundation; either
7 version 2.1 of the License, or (at your option) any later version.
9 This library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Lesser General Public License for more details.
14 You should have received a copy of the GNU Lesser General Public
15 License along with this library; if not, write to the Free Software
16 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
20 #ifndef ABSTRACTROUTINGENGINE_H
21 #define ABSTRACTROUTINGENGINE_H
23 #include <sys/types.h>
25 #include <boost/any.hpp>
30 #include "vehicleproperty.h"
31 #include "abstractpropertytype.h"
32 #include "propertyinfo.hpp"
36 class AsyncPropertyReply;
37 class AsyncRangePropertyReply;
38 class AsyncSetPropertyRequest;
41 typedef std::function<void (AsyncPropertyReply*)> GetPropertyCompletedSignal;
42 typedef std::function<void (AsyncRangePropertyReply*)> GetRangedPropertyCompletedSignal;
45 * \brief The AsyncPropertyRequest class is used by sinks to request property values.
46 * \see AbstractRoutingEngine::getPropertyAsync
47 * \see AsyncPropertyReply
49 class AsyncPropertyRequest
52 AsyncPropertyRequest()
53 :property(VehicleProperty::NoValue),zoneFilter(Zone::None), timeout(10000)
58 AsyncPropertyRequest(const AsyncPropertyRequest &request)
60 this->property = request.property;
61 this->completed = request.completed;
62 this->sourceUuidFilter = request.sourceUuidFilter;
63 this->zoneFilter = request.zoneFilter;
64 this->timeout = request.timeout;
67 AsyncPropertyRequest & operator = (const AsyncPropertyRequest & other)
69 this->property = other.property;
70 this->completed = other.completed;
71 this->sourceUuidFilter = other.sourceUuidFilter;
72 this->zoneFilter = other.zoneFilter;
73 this->timeout = other.timeout;
78 virtual ~AsyncPropertyRequest() { }
81 * \brief property property to request.
83 VehicleProperty::Property property;
86 * \brief sourceUuidFilter the requesting sink should use this to filter on a specific source or leave blank to use any source
88 std::string sourceUuidFilter;
91 * \brief zoneFilter the requesting sink should use this if he wants to filter on a specific zone
93 Zone::Type zoneFilter;
96 * \brief completed the callback when the request has been completed.
98 GetPropertyCompletedSignal completed;
101 * \brief use to specify a timeout in ms for the request. When a timeout occurs, the 'completed' callback
102 * will be called with an error. @see AsyncPropertyReply
103 * default value is: 10000 ms
108 * \brief pid requesting process id
114 * \brief The AsyncPropertyReply class is used by sources to reply to Get and Set operations. The source should
115 * set success to true if the call is successful or 'false' if the request was not successful and set 'error'
116 * to the appropriate error.
117 * \see AbstractRoutingEngine::getPropertyAsync
118 * \see AsyncPropertyReply
119 * \see AbstractSource::Operations
120 * \see AbstractSource::getPropertyAsync
122 class AsyncPropertyReply: public AsyncPropertyRequest
125 AsyncPropertyReply();
127 AsyncPropertyReply(const AsyncPropertyRequest &request);
129 AsyncPropertyReply(const AsyncSetPropertyRequest &request);
131 virtual ~AsyncPropertyReply()
135 g_source_destroy(timeoutSource);
136 g_source_unref(timeoutSource);
141 * \brief The Error enum
152 * \brief value of the reply. This may be null if success = false. This is owned by the source.
154 AbstractPropertyType* value;
157 * \brief success indicates if the request was successfull or not. True means success. False means fail and the 'error'
158 * member should be set.
163 * \brief error contains the error if the request was not successful.\
170 GSource* timeoutSource;
174 * \brief The AsyncSetPropertyRequest class is used by sinks to set a property to the 'value'. The source will reply
175 * with a AsyncPropertyReply containing the new value or an error.
176 * \see AbstractRoutingEngine::setProperty
177 * \see AsyncPropertyReply
179 class AsyncSetPropertyRequest: public AsyncPropertyRequest
182 AsyncSetPropertyRequest()
188 AsyncSetPropertyRequest(const AsyncPropertyRequest &request)
189 :AsyncPropertyRequest(request), value(NULL)
194 virtual ~AsyncSetPropertyRequest()
200 * \brief value the new value to set the property to.
202 AbstractPropertyType* value;
206 * \brief The AsyncRangePropertyRequest class is used by sinks to request values within a time or sequence range
207 * \see AbstractRoutingEngine::getRangePropertyAsync
209 class AsyncRangePropertyRequest
212 AsyncRangePropertyRequest()
213 :zone(Zone::None), timeBegin(0), timeEnd(0), sequenceBegin(-1), sequenceEnd(-1)
218 AsyncRangePropertyRequest(const AsyncRangePropertyRequest &request)
220 this->properties = request.properties;
221 this->completed = request.completed;
222 this->timeBegin = request.timeBegin;
223 this->timeEnd = request.timeEnd;
224 this->sequenceBegin = request.sequenceBegin;
225 this->sequenceEnd = request.sequenceEnd;
226 this->sourceUuid = request.sourceUuid;
227 this->zone = request.zone;
230 virtual ~AsyncRangePropertyRequest() {}
233 * \brief properties list of properties to request
235 PropertyList properties;
238 * \brief sourceUuid if the sink wishes to request a specific source, this should be set to the uuid of the source.
240 std::string sourceUuid;
243 * \brief zone if the sink wishes to request a specific zone, this should be set to the desired zone .
248 * \brief completed callback that is called when the ranged request is complete. The reply from this request is passed
249 * into the completed call. The completed callback must free the reply before it returns or there will be a leak.
251 GetRangedPropertyCompletedSignal completed;
254 * \brief timeBegin set this to request values for the specified property beggining at this time. Time is seconds\
255 * since the unix epoc. Set this to '0' if you do not want values within a time range.
260 * \brief timeEnd set this to request values for the specified property beggining at this time. Time is seconds\
261 * since the unix epoc. Set this to '0' if you do not want values within a time range.
266 * \brief sequenceBegin set this to request values with a sequence >= to the sequenceBegin value. Set to -1 if
267 * you don't want values within a sequence ranges.
269 int32_t sequenceBegin;
272 * \brief sequenceEnd set this to request values with a sequence <= to the sequenceEnd value. Set to -1 if
273 * you don't want values within a sequence ranges.
278 * \brief pid requesting process id
284 * \brief The AsyncRangePropertyReply class is used by a source to reply to an AsyncRangePropertyRequest.
285 * the source should set success to 'true' and populate the 'values' member if the request was successful.
286 * If the request is not successful, 'success' should be set to 'false' and the 'error' member should be set.
288 class AsyncRangePropertyReply: public AsyncRangePropertyRequest
291 AsyncRangePropertyReply(AsyncRangePropertyRequest request)
292 :AsyncRangePropertyRequest(request), success(false)
297 ~AsyncRangePropertyReply()
299 for(auto itr = values.begin(); itr != values.end(); itr++)
308 * \brief error this is set if there was an error in the request. "success" will also be set to false.
310 AsyncPropertyReply::Error error;
313 * \brief values if the request was successful, this will contain a list of values meeting the criteria of the request.
315 std::list<AbstractPropertyType*> values;
318 * \brief success this will be true if the request was successful. If not, this is false and error is set.
323 class AbstractRoutingEngine
326 typedef std::function<void (AbstractPropertyType* value)> PropertyChangedType;
327 virtual ~AbstractRoutingEngine();
329 virtual void registerSource(AbstractSource* src) = 0;
330 virtual void updateSupported(PropertyList added, PropertyList removed, AbstractSource* source) = 0;
334 void updateProperty(VehicleProperty::Property property, AbstractPropertyType* value, std::string uuid)
336 DebugOut(DebugOut::Warning)<<"updateProperty(VehicleProperty::Property,AbstractPropertyType*,std::string) is deprecated. use new updateProperty(AbstractPropertyType*, const std::string &)"<<endl;
337 updateProperty(value,uuid);
340 virtual void updateProperty(AbstractPropertyType* value, const std::string &uuid) = 0;
341 virtual PropertyList supported() = 0;
344 virtual void registerSink(AbstractSink* self) = 0;
345 virtual void unregisterSink(AbstractSink* self) = 0;
348 * /brief sourcesForProperty
350 * /return list of source uuid's that support the "property"
352 virtual std::list<std::string> sourcesForProperty(VehicleProperty::Property property) = 0;
355 * /brief getPropertyAsync requests a property value from a source. This call has a timeout and the callback specified in the request will always be called.
356 * /see AsyncPropertyRequest
357 * /see AsyncPropertyReply.
358 * /param request requested property.
359 * /return AsyncPropertyReply. The returned AsyncPropertyReply is owned by the caller of getPropertyAsync.
360 * /example AsyncPropertyRequest request;
361 * request.property = VehicleProperty::VehicleSpeed
362 * request.completed = [](AsyncPropertyReply* reply)
364 * //you own the reply
367 * routingEngine->getPropertyAsync(request);
369 virtual AsyncPropertyReply * getPropertyAsync(AsyncPropertyRequest request) = 0;
372 * \brief getRangePropertyAsync is used for getting a range of properties that are within the specified time or sequence parameters.
373 * \param request the request containing the property and other information required by the query
374 * \return a pointer to the reply.
375 * \example AsyncRangePropertyRequest vehicleSpeedFromLastWeek;
377 * vehicleSpeedFromLastWeek.timeBegin = amb::currentTime() - 10;
378 * vehicleSpeedFromLastWeek.timeEnd = amb::currentTime();
380 * PropertyList requestList;
381 * requestList.push_back(VehicleProperty::VehicleSpeed);
382 * requestList.push_back(VehicleProperty::EngineSpeed);
384 * vehicleSpeedFromLastWeek.properties = requestList;
385 * vehicleSpeedFromLastWeek.completed = [](AsyncRangePropertyReply* reply)
387 * std::list<AbstractPropertyType*> values = reply->values;
388 * for(auto itr = values.begin(); itr != values.end(); itr++)
391 * DebugOut(1)<<"Value from past: ("<<val->name<<"): "<<val->toString()<<" time: "<<val->timestamp<<endl;
397 * routingEngine->getRangePropertyAsync(vehicleSpeedFromLastWeek);
400 virtual AsyncRangePropertyReply * getRangePropertyAsync(AsyncRangePropertyRequest request) = 0;
403 * \brief setProperty sets a property to a value.
404 * \see AsyncSetPropertyRequest
405 * \see AsyncPropertyReply
406 * \param request the request containing the property and the value to set
407 * \return a pointer to the reply which is owned by the caller of this method
410 virtual AsyncPropertyReply * setProperty(AsyncSetPropertyRequest request) = 0;
413 * \brief subscribeToProperty subscribes to propertyName. Value changes will be passed to callback.
414 * \param propertyName
416 * \param pid process id of the requesting application
417 * \return subscription handle
419 virtual uint subscribeToProperty(VehicleProperty::Property propertyName, PropertyChangedType callback, std::string pid="") = 0;
422 * \brief unsubscribeToProperty
425 virtual void unsubscribeToProperty(uint handle) = 0;
428 * \brief subscribeToProperty subscribe to changes made to a property value.
429 * \param propertyName name of the property to request a subscription for.
430 * \param self pointer to the sink who is subscribing.
432 * //somewhere in the sink:
433 * routingEngine->subscribeToProperty(VehicleProperty::EngineSpeed, this);
435 * //... elsewhere in the sink, this will be called when a property changes:
436 * void MySink::propertyChanged(const AbstractPropertyType* property)
438 * if(property->name == VehicleProperty::EngineSpeed)
444 virtual bool subscribeToProperty(VehicleProperty::Property propertyName, AbstractSink* self) = 0;
447 * \brief subscribeToProperty subscribe to changes made to a property value.
448 * \param propertyName name of the property to request a subscription for.
449 * \param sourceUuidFilter source UUID to filter. Only property updates from this source will be sent to the sink.
450 * \param self pointer to the sink who is subscribing.
452 virtual bool subscribeToProperty(VehicleProperty::Property propertyName, std::string sourceUuidFilter, AbstractSink *self) = 0;
455 * \brief subscribeToProperty subscribe to changes made to a property value.
456 * \param propertyName name of the property to request a subscription for.
457 * \param sourceUuidFilter source UUID to filter. Only property updates from this source will be sent to the sink.
458 * \param zoneFilter zone to filter. Only updates from this zone will be passed to the sink.
459 * \param self pointer to the sink who is subscribing.
461 virtual bool subscribeToProperty(VehicleProperty::Property propertyName, std::string sourceUuidFilter, Zone::Type zoneFilter, AbstractSink *self) = 0;
463 virtual bool unsubscribeToProperty(VehicleProperty::Property, AbstractSink* self) = 0;
465 virtual PropertyInfo getPropertyInfo(VehicleProperty::Property, std::string sourceUuid) = 0;
468 #endif // ABSTRACTROUTINGENGINE_H