// vim:expandtab:autoindent:tabstop=4:shiftwidth=4:filetype=c:
//
//Do not use "\section", "\subsection", or other page-related commands here as
//this file is inlined in the ISmbios.h file.
//
/** \page smbios_theory Smbios Table Overview
*
* <b>Theory of Operation</b>
*
* <p>The SmbiosTable is meant to model the system SMBIOS table as a standard
* C++ data object. The system SMBIOS table most closely resembles a C++ STL
* vector class that happens to be read-only (const). We have chosen to
* implement the ISmbiosTable class so that it follows closely the STL
* standard containers. If you have used iterators to traverse
* a vector, or the [] operator, then you should be able to use the
* ISmbiosTable easily. The only difference here is that the [] operator
* takes as input the \a type of smbios item you wish to pull from the
* table, rather than an array index.
*
* The SmbiosTable class maintains it's own buffer that mirrors the contents
* of the actual system SMBIOS table. This is for efficiency reasons, as the
* table has a max length of 64k, and each access of the table potentially
* has to do special OS calls to re-read the data. There is a de-cache and
* reset API to tell the class to re-read data from main memory for the case
* of SMBIOS tables that are dynamically updated by firmware.
*
* <b>Object Ownership Rules</b>
*
* There are several types of objects that client code will have to deal
* with. Described below are the ownership semantics for the following
* objects:
* \li smbios::SmbiosFactory
* \li smbios::ISmbiosTable
* \li smbios::ISmbiosItem
*
* smbios::SmbiosFactory objects are singleton objects and may not be deleted.
* The only way to safely reclaim memory from a factory is to run the
* ->reset() method call, which will delete the factory and any
* factory-owned ISmbiosTable instances.
*
* smbios::ISmbiosTable objects are owned by the SmbiosFactory if the table is
* created with the getSingleton() method call. The client should not
* attempt to keep Table references past the point where the factory is
* reset(). If you get the ISmbiosTable object via the
* makeNew() you own the resulting table object and must delete() it.
*
* smbios::ISmbiosItem objects that are given out in response to Queries
* (smbios::ISmbiosTable::operator[]()or the iterator object), are owned by
* the Table. The client should never attempt to A) keep Item references
* past the lifetime of the
* containing table, or B) delete the Item.
*
* <b>Class Heirarchy Description</b>
* <p> The class heirarchy is based upon ISmbiosTable at the top level. This
* class is a pure virtual Abstract Base Class that provides the public
* interfact that outside clients can use. All of the operations that you
* can do on the Table are modeled in the ISmbiosTable class.
*
* The inheritance heirarchy is based around the concept that, no matter
* which OS or platform you are running on, the actual table data and
* parsing is going to be exactly the same. Because of this, all operations
* that operate on table data (parsing header, parsing out items), are
* implemented in the SmbiosTable class, which is a direct subclass of
* ISmbiosTable.
*
* The next level of the heirarchy is where we abstract the different
* methods of actually getting the table. This layer is different among the
* different OSs. This layer is responsible for loading the data items in
* SmbiosTable, and is implemented in SmbiosTableFileIo and
* SmbiosTableMemory. These two classes either load data from a file or from
* memory, respectively. File loading is used in the unit tests.
*
* The last detail of the inheritance heirarchy is that the methods that use
* XML to assist in parsing smbios data are separated into their own class.
* This is done for space and dependency reasons. First, the smbios without
* xml parsing is smaller. Next, xml parsing implies an additional runtime
* dependency on xerces, which is the xml library we use to parse xml. The
* classes which implement this are SmbiosTableXml and
* SmbiosTableXmlOsSpecific
*
* <b>Using the ISmbiosTable interface</b>
*
* \dontinclude testStandalone.cpp
* To use the ISmbiosTable interface, first you must instantiate an object
* with an ISmbiosTable interface. Since ISmbiosTable is a pure abstract
* class, you cannot directly instantiate an object of this type. The way to
* get a pointer to an ISmbiosTable class is by using the SmbiosFactory.
* \skip BEGIN EXAMPLE factory
* \skipline //
* \until getFactory
*
* Once you have a pointer to an ISmbiosTable object, you normally want to
* find items of a given type. This example uses the XML enhanced method,
* looking up the text in the XML file and finding the corresponding item:
* \skipline smbios::ISmbiosTable::iterator
*
* After you have a pointer to an item, you can pull out information from
* that item. Again, the string is converted to an int inside the class by
* looking the text up in XML:
* \skipline getU8
*
* <b>Using the iterator interface</b>
* <p>When there is more than one item of a given type in the table and you
* want to get data from each one, you should use the iterator pattern.
*
* To use the iterator, you instantiate the table the same way using the factory:
* \dontinclude testStandalone.cpp
* \skip BEGIN EXAMPLE iterator
* \skipline //
* \until getSingleton
*
* You can then iterate over the list of items using a for() or while()
* loop. This example prints out each item to a stream:
* \skipline // iterate
* \until }
*
*
* \todo
* The last couple of things that need to be added to ISmbiosTable to
* complete the API are:
* \li Add accessor functions for the different header fields in the
* Smbios Table Entry Point.
* \li Add a function to explicitly check the checksums stored in the
* Entry Point.
*
* \todo
* Need to remove the itemList member variable from ISmbiosTable.
* It needs to be put into SmbiosTable (private implementation class),
* and we need to provide a set of functions that the iterator can use in
* its place.
*/
