Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

LOW_device.h

Go to the documentation of this file.
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

Generated on Sun Jan 12 21:07:43 2003 by doxygen1.2.13.1 written by Dimitri van Heesch, © 1997-2001