simthetic: simth::DeviceManager Class Reference

This class manages the device description files. It known about the standard search path for XML devicelist files. It can load specific files, or it can load all available files. In each case the available DeviceDescription's can be returned.

In any case, the XML file format for the devicelist files is specified by the DTD devicelist.dtd as replicated below. If you want to check whether a particular XML file adheres to this DTD, you can use the tool xmllint as follows:

   xmllint --valid --noout my-devicelist-file.xml

However, depending on your actual simthetic installation you might need to tell the xmllint tool where to find the DTD file. Either you symlink or copy it directly from simthetic's version of that file, or you set the environment varilable SGML_CATALOG_FILES to the simth-catalog.xml file from $prefix/share/simthetic as follows:

   export SGML_CATALOG_FILES=$prefix/share/simthetic/simth-catalog.xml 
   xmllint --catalogs --valid --noout my-devicelist-file.xml

where $prefix is the path that was specified at the ./configure argument --prefix; by default this is /usr/local

<!-- ............................................................ -->
<!-- 
Typical Invocation:
#  <!DOCTYPE devicelist PUBLIC 
#   "-//TUHH//Simthetic Devicelist V1.0//EN" 
#   "devicelist.dtd">

Purpose:

  This DTD was developed to specify the properties of a Device in the
  simulations system Simthetic. Basically, an XML file adhering to
  this XML should specify everything about a device that is needed by
  any GUI.
-->
<!-- ............................................................ -->

<!-- A devicelist file can include many device definitions. The
     include element (see explanation there) can appear file-wide here, or
     can appear in particular devices. -->
<!ELEMENT devicelist (include*, device*) >

<!-- Each device element describes one C++ class. The C++ typename has
     to appear in the type attribute. The libraryname attribute contains
     the name of the shared library this device is implemented in. The
     extends attribute contains the name of the C++ base class, if this
     device is derived from another one. The abstract attribute is true if
     the C++ class is an abstract class.  -->
<!ELEMENT device (include*, description, inputinterfaces?, 
                  outputinterfaces?, overriddenproperties?, propertylist?) >
<!ATTLIST device
   name CDATA #REQUIRED
   type ID #REQUIRED
   libraryname CDATA #REQUIRED
   extends CDATA #IMPLIED
   abstract (true|false) "false">

<!-- The include element should point to the file name that contains
     the devicelist of the base class. This is just for helping the
     DeviceManager finding all necessary xml files. -->
<!ELEMENT include (#PCDATA)>
<!ELEMENT description (#PCDATA)>

<!-- The input- and outputinterfaces describe all the interfaces of a
     device. The attribute "multiplied_by" contains the name of a
     property, which, if it is set, gives the number of multiple
     instances of this interface that will actually exist.
-->
<!ELEMENT inputinterfaces (interface*)>
<!ELEMENT outputinterfaces (interface*)>
<!ELEMENT interface (description?)>
<!ATTLIST interface 
   type CDATA #REQUIRED
   multiplied_by CDATA #IMPLIED>

<!-- Sometimes, a derived class will override properties of the base
     class by its own values as defined in the C++ code. The names of these
     properties are listed in this element. -->
<!ELEMENT overriddenproperties (value*)>

<!-- Most important for the definition of a useful simulation
     scenario: The propertylist describes all properties that are available
     in this device. The propertylist defined here is also directly used
     inside simthetic when the objects are created. -->
<!ELEMENT propertylist (property*)>

<!ELEMENT property (default?, description, option*)>
<!ATTLIST property
   name CDATA #REQUIRED
   type (bool | int | unsigned | double | complex | string | 
         list_string | enum | sequencelength | vector_octal_int |
         vector_double | octal_int ) #REQUIRED
   empty_default (true|false) "false"
   obsolete (true|false) "false"
   grouping CDATA #IMPLIED>

<!-- For most property types, the option element describes possible
     values that particularly make sense for this property (please add
     appropriate descriptions). But for properties of type 'enum' the
     semantics are different: For 'enum' properties, the property is only
     allowed to have values that are mentioned here as option elements. -->
<!ELEMENT option (value, description?)>

<!-- The default element simply contains a default value for a
     property. If it is empty and the property attribute empty_default is
     false, then this property has to be set in the simulation parameter
     file. -->
<!ELEMENT default (#PCDATA)>
<!ELEMENT value (#PCDATA)>

Member Typedef Documentation

EXPIMP_TEMPLATE template DLLIMPORT simth::DeviceManager::DDMap

This map type describes a set of mappings from a string to a DeviceDescription object.

You can iterate through this map as usual. But each returned iterator points to a std::pair and not directly to the DeviceDescription. To get the DeviceDescription object, you use iterator->second. For more information please check the documentation of std::map.

To retrieve one specific DeviceDescription from this map, you will do the following:

      DeviceDescription dd;
      DDMap ddmap = ...       // get this from the DeviceManager
      DDMap::const_iterator iter = ddmap.find("DeviceTypeName");
      if (iter != ddmap.end())
        dd = iter->second;

Constructor & Destructor Documentation

simth::DeviceManager::DeviceManager ( const std::string & folder = "" )

Constructor.

Parameters:

folder

Path to the system wide device description file folder. (usually something like "PREFIX/share/simthetic/devices"). If left empty, then the content of the macro DEVICE_PATH is used, which means $prefix/share/simthetic/devices.

Member Function Documentation

const std::string& simth::DeviceManager::folder

(

)

const throw ()

Returns path to the system wide device description folder, which was the argument to the constructor.

const Property::list_string& simth::DeviceManager::folderlist

(

)

const throw ()

Returns all paths to all device description folders, starting with the one which is searched first.

DDMap simth::DeviceManager::allAvailableDescriptions

(

)

throw (bad_device_file, bad_device_description, type_error)

Returns a big hash map of *all* devicedescriptions from all files. To retrieve one DeviceDescription from it, you would write

      DeviceManager dm;
      DeviceDescription dd;
      DDMap ddmap = dm.allAvailableDescriptions();
      DDMap::const_iterator iter = ddmap.find("DeviceClassName");
      if (iter != ddmap.end())
        dd = iter->second;

DeviceDescriptionList simth::DeviceManager::allDescriptionsFromFile

(

const std::string &

fname

)

throw (file_not_found, bad_device_file, bad_device_description, type_error)

This method reads an XML file and returns the DeviceDescription's for alle devices that are found in that file.

This method takes care of the device's inheritance by evaluating the tag property "extends". The properties of those base classes (if any) are added to the propertylist first. This function throws exceptions if:

the file could not be found
the file is not a valid XML file
an internal error occurred (should not happen, though ;-)

Returns:: list of descriptions of the devices

Parameters:

fname

name of the XML file which contains the definition of the device. If an absolute path is given, only this path will be tried. Otherwise the current working directory will be scanned first followed by the folder given to the constructor.

DeviceDescription simth::DeviceManager::descriptionFromFile	(	const std::string &	fname,
		const std::string &	dname
	)	throw (file_not_found, bad_device_file, device_not_found, type_error)

This method reads an XML file and returns the DeviceDescription of a given device.

This method takes care of the device's inheritance by evaluating the tag property "extends". The properties of those base classes (if any) are added to the list first. This function throws exceptions if:

the file could not be found
the file is not a valid XML file
the device could not be found
an internal error occurred (should not happen, though ;-)

Returns:: description of the device

Parameters:

	fname	name of the XML file which contains the definition of the device. If an absolute path is given, only this path will be tried. Otherwise the current working directory will be scanned first followed by the folder given to the constructor.
	dname	name of the device

Property::list_string simth::DeviceManager::allXMLFiles

(

)

const

This method returns a list of all XML files that can be found in the PATH.

static bool simth::DeviceManager::string_to_bool ( const std::string abstr ) [static]

Convert the XML boolean value to an actual bool


Public Types
typedef simth::DeviceDescription	DeviceDescription
typedef std::string	DDMapKey
typedef std::map< DDMapKey, DeviceDescription >	DDMap
typedef std::vector< DeviceDescription >	DeviceDescriptionList
Public Member Functions
	DeviceManager (const std::string &folder="")
virtual	~DeviceManager ()
const std::string &	folder () const throw ()
const Property::list_string &	folderlist () const throw ()
DDMap	allAvailableDescriptions () throw (bad_device_file, bad_device_description, type_error)
DeviceDescriptionList	allAvailableDescriptionsList () throw (bad_device_file, bad_device_description, type_error)
DeviceDescriptionList	allDescriptionsFromFile (const std::string &fname) throw (file_not_found, bad_device_file, bad_device_description, type_error)
DeviceDescription	descriptionFromFile (const std::string &fname, const std::string &dname) throw (file_not_found, bad_device_file, device_not_found, type_error)
Property::list_string	allXMLFiles () const
Static Public Member Functions
Internal helpers
static bool	string_to_bool (const std::string abstr)
Friends
class	DeviceManagerPriv

simth::DeviceManager Class Reference

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation