1.0 IntroductionThis is a summary of some of the general details of the way the Linuxcareproviders have been written.In producing providers we have decided to break the implementation out intoseveral different major functional groups.  These groups are the provider interface classes themselves, the classes providing the bulk of the implementation and any support classes necessary.  These groups are implemented using four different class types.2.0 CIMInstanceProvider ClassesThe first set of classes are derived from CIMInstanceProvider and the otherPegasus provider base classes.  The classes derived fromCIMInstanceProvider are considered the providers themselves in the Pegasusnomenclature.  Pegasus instantiates these classes by calling thePegasusCreateProvider function for the appropriate class name.  The generalphilosophy has been to ensure that as little work as possible is done inthese classes.  As a rule, a provider constructs "ProviderData" objects,and calls methods within those objects to fill in instances and references.This makes the providers exceedingly lightweight, which helps to insulateagainst changes to the provider API.3.0 ProviderData ClassesThe second set of classes are derived from ProviderData.  These classes contain the bulk of the implementation of the providers including locating all instances and returning all of the information for a particularinstance.  These classes can in turn call other classes to assist in that process.  Insome cases it might be that the ProviderData classes are themselves verythin and only wrap another class that performs all the work.  In this caseit is still required to have the ProviderData class to maintain aconsistant view of providers to Pegasus.  The intention is that theCIMInstanceProvider classes will all be thin wrappers around theProviderData classes regardless of how the ProviderData classes areimplemented.The ProviderData classes are intended to be closely related to the WBEMschema, usually leading to a simple pairing of one WBEM class with oneProviderData class.  Sometimes it is appropriate to have more than one WBEMclass per ProviderData class where the differences between the two WBEMclasses are trivial.  This rule also holds for the CIMInstanceProviderclasses as well.4.0 ProviderSupport ClassesThe next set of classes are call ProviderSupport classes.  These classescontain code that is common between different types of ProviderDataclasses.  Currently the two different classes that fall into this categoryare the DeviceLocator and the FileReader.  Each of these classes iscurrently used by several ProviderData classes.4.1 DeviceLocatorAn entire category of WBEM data is obtained by examining the contents of various buses on the currently running system.  A DeviceLocator class was created to perform generic searches of this type, and this class returns objects from a DeviceInformation class.  For providers interested in this category of WBEM data, the ProviderData object creates DeviceLocator objects, uses them to retrieve DeviceInformation objects, and uses the data contained therein, possibly supplementing it with additional data from other sources.The DeviceLocator class is used by submitting a search criteria and thenrequesting all devices that match the specific criteria.  4.1.1 Search CriteriaThe search criteria is a hierarchial set of device and system resourcetypes.  The list was obtained initially from the PCI device clasificationand was further added to by specific system resources.  A perl script'generateDeviceTypes.pl' is used to generate the list from the PCIinformation in /usr/share/pci.ids as well as the system resourcesinformation in pegasus.ids.4.1.2 DeviceLocator PluginsThe DeviceLocator class is a wrapper class around plugins for specificdevices on the system.  Each plugin follows an API that the DeviceLocatordictates.  When a ProviderData class requests information about a specifictype of device, the DeviceLocator initializes each plugin in turndetermining which plugins can be used to search for that device type.Which devices and what device information any particular plugin supportsare up to the developer of the plugin and will be influenced by the WBEMSchema and the specific information that is available on the system.  Eachplugin returns information in an object instantiated from a class derivedfrom DeviceInformation.  A pointer to this object is passed back to theuser of the DeviceLocator object, and the user is responsible for deletingthis pointer when he has finished using the information contained in it.4.1.3 DeviceInformation ClassesThe DeviceInformation classes are used to return information about thespecific device types.  The information returned in these classes caneither be specific to the DeviceLocator plugin, to the WBEM schema or a combination of the two.  The specific implementation is left to thedeveloper.  The intention is that the developer of the ProviderData classwill also develop the DeviceLocator plugin.  This is reasonable becausethe two are so closely related.  This class is used to pass information from the plugin to the user of theDeviceLocator.  It is not intended that the DeviceInformation classesalways mirror exactly their corresponding schema, but in some cases itmight be convenient that they do so.  Some DeviceLocator plugins map verywell to the WBEM schema while others comprise only a subsection of one WBEMclass, or aggregate several WBEM classes.  In these cases modeling theDeviceInformation classes after the plugin is more appropriate, letting theProviderData class handle the amalgamation or extraction of the appropriateinformation for the specific WBEM class.4.2 FileReaderMuch of the WBEM data is obtained by parsing files or the output ofexecuted system binaries.  A FileReader class was created to produce anabstraction that would simplify this parsing.  At present, there are twosuch parsers, FileScanner, which searches for files, then scans thecontents of the files located, and ExecScanner, which executes a binary andparses the standard output stream from that binary.  Both of these classesare derived from an abstract base class, StreamScanner.4.2.1 StreamScannerThe StreamScanner class parses the text stream associated with a FILE*handle.  The stream to parse must be set by a derived class.  TheStreamScanner object can then be given a set of regular expressions tosearch in the stream.  The stream is loaded, one line at a time, and eachline is compared against all regular expressions.  When a match is found,the line is returned to the caller, along with, optionally, the index ofthe regular expression from the search set which matched the line and avector<> of String objects holding substring matches if those werespecified in the regular expression.  The regular expression set can bechanged after any match, so that the choice of regular expressions is madeby a programmed state machine, or the set can be reused for the duration ofthe stream.  The file pointer in the stream is never rewound, each line isread exactly once.  When the end of file is reached, that is signaled tothe caller.4.2.2 FileScannerThe FileScanner class searches the directory tree under a given directoryfor regular files which match any of a set of regular expressions.  Theorder in which filenames are examined is unordered within a directory, andin a depth-first manner when encountering subdirectories.  Once a file islocated, the filename is returned to the user and the StreamScannercomponents are prepared for parsing the contents of the file.  The user maynow set the regular expressions used for searching the contents of thefile, possibly based on the filename returned.  When the end of the streamis encountered, the caller is informed, and the caller may then choose toresume the file search.4.2.3 ExecScannerThe ExecScanner class executes a command and passes the standard outputstream of that command to the StreamScanner components for parsing.5.0 Programming StylesSeveral different programming styles and approaches were used in the files.The intention is to demonstrate a variety of solutions so that therecipient can choose a comfortable style, and so that the necessaryimmutable components of the system are easier to pick out from thecomponents which the programmer is free to treat differently.The first set of providers implemented were the OperatingSystem providerand the SoftwareElement provider.  The first set of providers to use theDevice locator were the Processor provider and the DiskDrive provider.  Thelatest providers, which follow the design that we feel is the mostappropriate, are the PCIController provider and the NetworkAdapterprovider.6.0 Further RecommendationsAfter the experimentation with these different programming approaches, wehave settled on a recommended standard for future providers.  Not all theproviders written so far follow this standard, but it is expected thatfuture providers would benefit from doing so.  These recommendations are:- Provider classes have no direct access to DeviceInformation or  DeviceLocator classes, they work only through ProviderData.- Provider classes are otherwise extremely thin.- Providers for a CIM class, when asked to fill an instance, request every  unpropagated CIM variable for the class and its parent classes, by  calling a method within the appropriate ProviderData objects, that method  being named "Get<<CIM_variable_name>>()".  They do this in a try{} block,  catching and ignoring the "AccessedInvalidData" exception.  The  ProviderData class is required to define every CIM variable, but those  which it may not be able to set it should make a validated<TYPE>.  That  type will throw the exception when accessed, allowing the provider to  skip over fields which are uninitialized without the programmer having to  reserve special "invalid data" values in the type.  The advantage of this  approach is that, should the previously unavailable data be made  available by a later tool, the programmer has only to code in a  validated<TYPE>.setValue() call in the ProviderData class, and it will  automagically be inserted into the filled instance without any further  coding being required.7.0 Directory StructureAll of the classes discussed above are placed under the pegasus/src/Providers directory.  Directory layout for that directory is as follows:pegasus/src/Providers	Most of the changes took place under this directory.pegasus/src/Providers/CIMInstanceProvider	New providers were written here.  Each provider binary is built in	a separate directory.pegasus/src/Providers/CIMProvider	Obsoletepegasus/src/Providers/Include	Holds generic .h files which might be used in more than one	location within ProviderData, ProviderSupport, or	CIMInstanceProvider.  Any classes defined here (such as some	generic parent classes like LogicalDevice) must not use a .cpp	file, their methods are all inlined into the class definition in	the .h file.pegasus/src/Providers/ProviderData	Holds ProviderData class definitions, used by providers.pegasus/src/Providers/ProviderSupport	A generic location for utilities of possible use to ProviderData	classes.pegasus/src/Providers/ProviderSupport/DeviceLocator	The bus scanning routines.  The DeviceLocator object returns	pointers to DeviceInformation objects.pegasus/src/Providers/ProviderSupport/FileReader	A pair of very useful support methods.  One does a recursive search	on a directory, scanning for files whose names match one of a set	of given regular expressions.  For each file located, the invoker	gets the name of the file, and can request a search of the contents	of the file, looking for other regular expressions.  Substrings of	the regular expressions are then returned in an array for easy	analysis.  The other method is exactly the same, but rather than	searching a directory, it executes a named binary and parses the	output of the binary.