/usr/include/x86_64-linux-gnu/alljoyn/Observer.h is in liballjoyn-dev-1604 16.04a+dfsg.1-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 | #ifndef _ALLJOYN_OBSERVER_H
#define _ALLJOYN_OBSERVER_H
/**
* @file
* This file defines the class Observer.
* An Observer takes care of discovery, session management and ProxyBusObject
* creation for bus objects that implement a specific set of interfaces.
*/
/******************************************************************************
* Copyright AllSeen Alliance. All rights reserved.
*
* Permission to use, copy, modify, and/or distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
******************************************************************************/
#include <qcc/String.h>
#include <alljoyn/InterfaceDescription.h>
#include <alljoyn/ProxyBusObject.h>
#include <alljoyn/BusAttachment.h>
#include <alljoyn/Status.h>
namespace ajn {
/**
* ObjectId is a simple encapsulation of a bus object's unique name and object path.
*
* It represents the unique identity of any object on the AllJoyn bus.
*/
struct ObjectId {
/**
* Unique bus name (never a well-known name!) of the peer hosting this object.
*/
qcc::String uniqueBusName;
/**
* Path of the object.
*/
qcc::String objectPath;
/**
* Default constructor.
*
* Creates an invalid object id.
*/
ObjectId();
/**
* Constructor.
*
* @param busname Unique(!) bus name of the peer hosting the object.
* @param path Object path
*/
ObjectId(const qcc::String& busname, const qcc::String& path);
/**
* Constructor.
*
* @param ppbo ProxyBusObject* for which to construct an object id
*/
ObjectId(const ProxyBusObject* ppbo);
/**
* Constructor.
*
* @param pbo ProxyBusObject for which to construct an object id
*/
ObjectId(const ProxyBusObject& pbo);
/**
* Copy Constructor.
*
* @param other the ObjectId to copy
*/
ObjectId(const ObjectId& other);
/**
* The assign operator for ObjectId
*
* @param other the ObjectId to assign to this ObjectId
*
* @return a reference to this ObjectId.
*/
ObjectId& operator=(const ObjectId& other);
/**
* Equals operator for the ObjectId
*
* @param other the ObjectId to check for equality
*
* @return true it the two objects are equal
*/
bool operator==(const ObjectId& other) const;
/**
* less than operator for the ObjectId
*
* @param other the ObjectId to check it this object is less than
*
* @returns true if this object is less than other
*/
bool operator<(const ObjectId& other) const;
/**
* Check validity of the object path
*/
bool IsValid() const;
};
/**
* An Observer takes care of discovery, session management and ProxyBusObject
* creation for bus objects that implement a specific set of interfaces.
*
* The Observer monitors About announcements, and automatically sets up sessions
* with all peers that offer objects of interest (i.e. objects that implement at
* least the set of mandatory interfaces for this Observer). The Observer creates
* a proxy bus object for each discovered object. The Observer::Listener class
* is used to inform the application about the discovery of new objects, and about
* the disappearance of objects from the bus.
*
* Objects are considered lost in the following cases:
* - they are un-announced via About
* - the hosting peer has closed the session
* - the hosting peer stopped responding to Ping requests
*/
class Observer {
public:
/**
* Constructor.
*
* @param bus Bus attachment to which the Observer is attached.
* @param mandatoryInterfaces Set of interface names that a bus object
* MUST implement to be discoverable by this Observer.
* @param numMandatoryInterfaces number of elements in the mandatoryInterfaces array.
*
* Some things to take into account:
* - the Observer will only discover objects that are announced through About.
* - the interface names in mandatoryInterfaces must correspond with
* InterfaceDescriptions that have been registered with the bus
* attachment before creation of the Observer.
* - mandatoryInterfaces must not be empty or NULL
*/
Observer(BusAttachment& bus,
const char* mandatoryInterfaces[], size_t numMandatoryInterfaces);
/**
* Destructor.
*/
~Observer();
/**
* Abstract base class implemented by the application and called by the
* Observer to inform the application about Observer-related events.
*/
class Listener {
public:
virtual ~Listener() { }
/**
* A new object has been discovered.
*
* @param object a proxy bus object supporting announced in the About signal
*/
virtual void ObjectDiscovered(ProxyBusObject& object) { QCC_UNUSED(object); };
/**
* A previously discovered object has been lost.
*
* @param object the proxy bus object representing the object that
* has been lost.
*
* Note that it is no longer possible to perform method calls (RPCs) on
* this proxy object. If the object reappears, a new proxy object will
* be created.
*/
virtual void ObjectLost(ProxyBusObject& object) { QCC_UNUSED(object); };
};
/**
* Register a listener.
*
* @param listener the listener to register
* @param triggerOnExisting trigger ObjectDiscovered callbacks for
* already-discovered objects
*/
void RegisterListener(Listener& listener, bool triggerOnExisting = true);
/**
* Unregister a listener.
*
* @param listener the listener to unregister
*/
void UnregisterListener(Listener& listener);
/**
* Unregister all listeners.
*
* There is no real need to unregister all listeners before the Observer
* is destroyed, but it is considered good style to do so.
*/
void UnregisterAllListeners();
/*
* All methods below that return ProxyBusObjects will return an
* invalid object if appropriate (if there is no object with this ObjectId
* or when the iteration is finished). This can be checked with the
* ProxyBusObject::IsValid() method
*/
/**
* Get a proxy object.
*
* @param oid The object id of the object you want to retrieve.
*
* @return the proxy object with the requested ObjectId
*
* This call will always return a ProxyBusObject, even if the Observer
* has not discovered the object you're looking for. In that case, an invalid
* ProxyBusObject will be returned. You can check this condition with
* the ProxyBusObject::IsValid() method.
*/
ProxyBusObject Get(const ObjectId& oid);
/**
* Get a proxy object.
*
* @param uniqueBusName The unique bus name of the peer hosting the object
* you want to retrieve.
* @param objectPath The path of the object you want to retrieve.
*
* @return The discovered proxy object.
*
* This call will always return a ProxyBusObject, even if the Observer
* has not discovered the object you're looking for. In that case, an invalid
* ProxyBusObject will be returned. You can check this condition with
* the ProxyBusObject::IsValid() method.
*/
ProxyBusObject Get(const qcc::String& uniqueBusName, const qcc::String& objectPath) {
return Get(ObjectId(uniqueBusName, objectPath));
}
/**
* Get the first proxy object.
*
* The GetFirst/GetNext pair of methods is useful for iterating over all discovered
* objects. The iteration is over when the proxy object returned by either call is
* not valid (see ProxyBusObject::IsValid).
*
* @return the first proxy object found in the observer
*/
ProxyBusObject GetFirst();
/**
* Get the next proxy object.
*
* The GetFirst/GetNext pair of methods is useful for iterating over all discovered
* objects. The iteration is over when the proxy object returned by either call is
* not valid (see ProxyBusObject::IsValid).
*
* @param oid This method will return the proxy object immediately following the one
* with this object id.
* @return the proxy object immediately following the one identified by the oid object id
*/
ProxyBusObject GetNext(const ObjectId& oid);
/**
* Get the next proxy object.
*
* The GetFirst/GetNext pair of methods is useful for iterating over all discovered
* objects. The iteration is over when the proxy object returned by either call is
* not valid (see ProxyBusObject::IsValid).
*
* @param mpbo This method will return the proxy object immediately following this one
*
* @return the proxy object immediately following the mpbo proxy object
*/
ProxyBusObject GetNext(const ProxyBusObject& mpbo) {
return GetNext(ObjectId(mpbo));
}
class Internal;
private:
Internal* internal;
/* no copy constructors or assignment */
Observer(const Observer& other);
Observer& operator=(const Observer& other);
};
}
#endif
|