00001 /*************************************************************************** 00002 LOW_device.h - description 00003 ------------------- 00004 begin : Sat Jul 6 2002 00005 copyright : (C) 2002 by Harald Roelle, Helmut Reiser 00006 email : roelle@informatik.uni-muenchen.de, reiser@informatik.uni-muenchen.de 00007 ***************************************************************************/ 00008 00009 /*************************************************************************** 00010 * * 00011 * This program is free software; you can redistribute it and/or modify * 00012 * it under the terms of the GNU General Public License as published by * 00013 * the Free Software Foundation; either version 2 of the License, or * 00014 * (at your option) any later version. * 00015 * * 00016 ***************************************************************************/ 00017 00018 #ifndef LOW_DEVICE_H 00019 #define LOW_DEVICE_H 00020 00021 00022 #include <map> 00023 00024 #include "LOW_link.h" 00025 #include "LOW_deviceID.h" 00026 #include "LOW_exception.h" 00027 00028 00029 class LOW_netSegment; // forward declaration needed to resolve circular definitions. 00030 class LOW_network; // forward declaration needed to resolve circular definitions. 00031 00032 00033 /** Abstract base class for all 1-Wire devices. 00034 00035 Any device class representing a concrete 1-Wire device must inherit from this class. 00036 00037 @author Harald Roelle, Helmut Reiser 00038 */ 00039 class LOW_device { 00040 00041 //======================================================================================= 00042 public: 00043 00044 //===================================================================================== 00045 // 00046 // exceptions 00047 // 00048 00049 /** Exception base class for all exceptions thrown by LOW_device. */ 00050 class_DERIVE_FROM_EXCEPTION( device_error, LOW_exception); 00051 00052 /** Exception class indicating a mismatch of expected/required family code. */ 00053 class_DERIVE_FROM_EXCEPTION( familyMismatch_error ,device_error); 00054 00055 /** Exception class indicating that the requested or any device could not be found. 00056 This exception is also used by many other classes. 00057 */ 00058 class_DERIVE_FROM_EXCEPTION( noDevice_error ,device_error); 00059 00060 /** Exception class indicating that an illegal dynamic type cast on a device occured. 00061 This exception is also used by many other classes. 00062 */ 00063 class_DERIVE_FROM_EXCEPTION( illegalCast_error ,device_error); 00064 00065 00066 //===================================================================================== 00067 // 00068 // constants 00069 // 00070 00071 /** Family code for selecting any/all device types. */ 00072 static const LOW_deviceIDRaw::devFamCode_t anyDev_famCode = 0xff; 00073 00074 /** Family code of this base class equals the one for any device type. 00075 <B>Note:</B> Any subclass must override this constant. 00076 */ 00077 static const LOW_deviceIDRaw::devFamCode_t familyCode = anyDev_famCode; 00078 00079 /** Family name of this base class. 00080 <B>Note:</B> Any subclass must override this constant. 00081 */ 00082 static const string familyName; 00083 00084 static const owCommand_t MatchROM_COMMAND = 0x55; /**< 1-Wire command byte constant */ 00085 static const owCommand_t ReadROM_COMMAND = 0x33; /**< 1-Wire command byte constant */ 00086 static const owCommand_t SkipROM_COMMAND = 0xcc; /**< 1-Wire command byte constant */ 00087 static const owCommand_t SearchROM_COMMAND = 0xf0; /**< 1-Wire command byte constant */ 00088 static const owCommand_t SearchAlarmROM_COMMAND = 0xec; /**< 1-Wire command byte constant */ 00089 00090 00091 //===================================================================================== 00092 // 00093 // type definitions 00094 // 00095 00096 typedef std::vector<LOW_device*> devPtrVec_t; /**< Vector type of class device pointers. */ 00097 typedef std::map<LOW_deviceID,LOW_device*> deviceMap_t; /**< Map type of devices with LOW_deviceID as key. */ 00098 00099 00100 //===================================================================================== 00101 // 00102 // classes 00103 // 00104 00105 /** Locking class to ensure exclusive access to a device. 00106 00107 The class is intended to be used in a "locking is creation" design pattern. 00108 On creation an exclusive loxk is optained for the device, and on destruction 00109 the lock is released. 00110 00111 Implemented by obtaining a LOW_link::commLock for the link the device is on. 00112 */ 00113 class linkLock : public LOW_link::commLock 00114 { 00115 public: 00116 /** Obtain the lock. 00117 00118 @param inDev Reference to the device to obtain the lock for. 00119 */ 00120 linkLock( const LOW_device &inDev); 00121 00122 /** Release the lock. */ 00123 ~linkLock(); 00124 }; 00125 00126 00127 //===================================================================================== 00128 // 00129 // constructors 00130 // 00131 00132 /** Destructor. 00133 Deregisters the device from its LOW_netSegment. 00134 */ 00135 virtual ~LOW_device(); 00136 00137 00138 //===================================================================================== 00139 // 00140 // methods 00141 // 00142 00143 /** Get the device's ROM ID. 00144 @return ROM ID of the device. 00145 */ 00146 LOW_deviceID getID() const; 00147 00148 /** Get the network segment the device is on. 00149 @return Nnetwork segment the device is on. 00150 */ 00151 LOW_netSegment& getNetSegment() const; 00152 00153 /** Get the device's family name. 00154 <B>Note:</B> Subclasses must implement this method to return a clear test 00155 name of their family. 00156 @return Family name of the device. 00157 */ 00158 virtual string getFamilyName() const { return familyName; }; 00159 00160 /** Shortcut method to verify the presence of the device on it's network segment. 00161 @see LOW_netSegment::verifyDevice() 00162 */ 00163 bool verifyDevice( const bool inOnlyAlarm = false, const bool inDoReset = true) const; 00164 00165 00166 //======================================================================================= 00167 protected: 00168 00169 //===================================================================================== 00170 // 00171 // friends 00172 // 00173 00174 friend class linkLock; /**< Needed to grant access to the protected getLink() method. */ 00175 00176 00177 //===================================================================================== 00178 // 00179 // attributes 00180 // 00181 00182 const LOW_deviceID ID; /**< 1-Wire ROM ID of the device. */ 00183 LOW_netSegment &netSegment; /**< Network segment where the device is located. */ 00184 00185 00186 //===================================================================================== 00187 // 00188 // constructors 00189 // 00190 00191 /** Base constructor for devices. 00192 00193 <B>Note:</B> In asymmetry to the destructor no action regarding the 00194 network segment's device maps is done here. This is already 00195 performed by LOW_netSegment. 00196 00197 @param inSegment Reference to the network segment the device is on. 00198 @param inDevID Reference to device's ID. 00199 @param inFamCode Expected familiy code for the device. 00200 @throw familyMismatch_error Thrown when <I>inFamCode</I> and familiy code 00201 of <I>inDevID</I> don't match. 00202 */ 00203 LOW_device( LOW_netSegment &inSegment, const LOW_deviceID &inDevID, 00204 const LOW_deviceIDRaw::devFamCode_t inFamCode); 00205 00206 00207 //===================================================================================== 00208 // 00209 // static methods 00210 // 00211 00212 /** Static method for creating new concrete device objects. 00213 This method is de-facto virtual as no implementation is given here 00214 and so it must be implemented individually by every subclass. 00215 The returned object must be dynamically allocated (i.e. it must 00216 be disposable by the delete operator). 00217 00218 @param inNetSegment Reference to the network segment the device is on. 00219 @param inDevID Reference to the device's ID. 00220 @returns The new dynamically created device instance. 00221 */ 00222 static LOW_device* new_Instance( LOW_netSegment &inNetSegment, const LOW_deviceID &inDevID); 00223 00224 00225 //===================================================================================== 00226 // 00227 // methods 00228 // 00229 00230 /** Get the link the device is on. 00231 @return Link the device is on. 00232 */ 00233 LOW_link& getLink() const; 00234 00235 /** Shortcut for issuing a matchROM command for a device. 00236 Calls the corresponding method in LOW_netSegment. 00237 */ 00238 void cmd_MatchROM() const; 00239 00240 }; 00241 00242 00243 #endif