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
00006     email                : roelle@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_deviceIDRaw.h"
00026 #include "LOW_deviceID.h"
00027 #include "LOW_exception.h"
00028 
00029 class LOW_netSegment;  // forward declaration needed to resolve circular definitions.
00030 
00031 
00032 /** Abstract base class for all 1-Wire devices.
00033 
00034     Any device class representing a concrete 1-Wire device must inherit from this class.
00035 
00036     This class is thread-safe.
00037 
00038     @author Harald Roelle
00039  */
00040 class LOW_device {
00041 
00042 //=======================================================================================
00043 public:
00044   
00045   //=====================================================================================
00046   //
00047   // exceptions
00048   //
00049  
00050   /** Exception base class for all exceptions thrown by LOW_device. */
00051   class_DERIVE_FROM_EXCEPTION( device_error, LOW_exception);
00052 
00053   /** Exception class indicating a mismatch of expected/required family code. */
00054   class_DERIVE_FROM_EXCEPTION( familyMismatch_error, device_error);
00055 
00056   /** Exception class indicating that the requested or any device could not be found.
00057       This exception is also used by many other classes.
00058    */
00059   class_DERIVE_FROM_EXCEPTION( noDevice_error, device_error);
00060 
00061   /** Exception class indicating that an illegal dynamic type cast on a device occured.
00062       This exception is also used by many other classes.
00063    */
00064   class_DERIVE_FROM_EXCEPTION( illegalCast_error, device_error);
00065 
00066   
00067   //=====================================================================================
00068   //
00069   // constants
00070   //
00071 
00072   /** Family code for selecting any/all device types. */
00073   static const LOW_deviceIDRaw::devFamCode_t anyDev_famCode = 0xff;
00074   
00075   /** Family code of this base class equals the one for any device type.
00076       <B>Note:</B> Any subclass must override this constant.
00077    */
00078   static const LOW_deviceIDRaw::devFamCode_t familyCode = anyDev_famCode;
00079 
00080   /** Family name of this base class.
00081       <B>Note:</B> Any subclass must override this constant.
00082    */
00083   static const std::string familyName;
00084 
00085   static const owCommand_t  MatchROM_COMMAND         = 0x55; /**< 1-Wire command byte constant */
00086   static const owCommand_t  ReadROM_COMMAND          = 0x33; /**< 1-Wire command byte constant */
00087   static const owCommand_t  SkipROM_COMMAND          = 0xcc; /**< 1-Wire command byte constant */
00088   static const owCommand_t  SearchROM_COMMAND        = 0xf0; /**< 1-Wire command byte constant */
00089   static const owCommand_t  SearchAlarmROM_COMMAND   = 0xec; /**< 1-Wire command byte constant */
00090   
00091   
00092   //=====================================================================================
00093   //
00094   // type definitions
00095   //
00096   
00097   typedef std::vector<LOW_device*>            devPtrVec_t;  /**< Vector type of class device pointers. */
00098   typedef std::map<LOW_deviceID,LOW_device*>  deviceMap_t;  /**< Map type of devices with LOW_deviceID as key. */
00099   
00100   
00101   //=====================================================================================
00102   //
00103   // classes
00104   //
00105 
00106   /** Locking class to ensure exclusive access to a device.
00107 
00108       The class is intended to be used in a "locking is creation" design pattern.
00109       On creation an exclusive loxk is optained for the device, and on destruction
00110       the lock is released.
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   virtual LOW_deviceID getID() const;
00147 
00148   /** Get the network segment the device is on.
00149       @return Nnetwork segment the device is on.
00150    */
00151   virtual 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 std::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   virtual 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   virtual 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   virtual void cmd_MatchROM() const;
00239 
00240 };
00241 
00242 
00243 #endif

Generated on Mon Oct 27 22:56:08 2003 by doxygen1.2.13.1 written by Dimitri van Heesch, © 1997-2001