Main Page | Namespace List | Class Hierarchy | Class List | File List | Namespace Members | Class Members | File Members | Related Pages

ISmbiosTable Class Reference

Interface definition for Smbios Table operations. More...

#include <ISmbios.h>

Inheritance diagram for ISmbiosTable:

SmbiosTable SmbiosTableXml SmbiosTableXml List of all members.

Public Types

typedef SmbiosTableIterator iterator
typedef ConstSmbiosTableIterator const_iterator

Public Member Functions

 ISmbiosTable ()
virtual ~ISmbiosTable ()
virtual iterator begin ()=0
 Standard iterator interface. Points to first table item.

virtual const_iterator begin () const=0
 Standard iterator interface. Points to first table item.

virtual iterator end ()=0
 Standard iterator interface. Points to one-past-the-last table item.

virtual const_iterator end () const=0
 Standard iterator interface. Points to one-past-the-last table item.

virtual iterator operator[] (const int)=0
 Standard indexed access by integer item type.

virtual const_iterator operator[] (const int) const=0
 Standard indexed access by integer item type.

virtual iterator operator[] (const std::string &)=0
 Standard indexed access by string description. XML ENHANCED.

virtual const_iterator operator[] (const std::string &) const=0
 Standard indexed access by string description. XML ENHANCED.

virtual void rawMode (bool m=true) const=0
 Disables all workarounds for _new_ items created by the table.

virtual void clearItemCache () const=0
 Clears out any cached SmbiosItem entries in the cache.

virtual void reReadTable ()=0
 Re-Read the table from memory. Invalidates all existing ISmbiosItems.

virtual int getNumberOfEntries () const=0
 Returns the number of table items, per SMBIOS table header.

virtual smbiosLowlevel::smbios_table_entry_point getTableEPS () const=0
 Returns the table entry point structure.

virtual std::ostream & streamify (std::ostream &cout) const=0
 Used by operator << (std::ostream & cout, const ISmbiosTable & ) to.


Private Member Functions

 ISmbiosTable (const ISmbiosTable &)
 not implemented (explicitly disallowed)

void operator= (const ISmbiosTable &)
 not implemented (explicitly disallowed)


Detailed Description

Interface definition for Smbios Table operations.

Theory of Operation

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 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.

Object Ownership Rules

There are several types of objects that client code will have to deal with. Described below are the ownership semantics for the following objects:

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.

Class Heirarchy Description

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

Using the ISmbiosTable interface

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.

    // BEGIN EXAMPLE factory
    // table should not be deleted when we are finished. It is managed by the
    // factory. Factory will delete it for us when ->reset() is called.
    smbios::ISmbiosTable *table =
        smbios::SmbiosFactory::getFactory()->getSingleton();

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:

    smbios::ISmbiosTable::iterator item1 = (*table)["BIOS Information"];

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:

    u1 = getU8_FromItem(*item1, "Type");

Using the iterator interface

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:

    // BEGIN EXAMPLE iterator
    // table should not be deleted when we are finished. It is managed by the
    // factory. Factory will delete it for us when ->reset() is called.
    smbios::ISmbiosTable *table =
        smbios::SmbiosFactory::getFactory()->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:

    // iterate over all PORT INFORMATION BLOCKS
    for( smbios::ISmbiosTable::iterator item = (*table)[8] ; item != table->end(); ++item)
    {
        ost << *item << endl;
    }

Todo:
The last couple of things that need to be added to ISmbiosTable to complete the API are: 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.

Definition at line 117 of file ISmbios.h.


Member Typedef Documentation

typedef ConstSmbiosTableIterator const_iterator
 

Definition at line 123 of file ISmbios.h.

Referenced by TokenTable::addChecksumObserverForD4Struct(), TokenTable::addD4Structures(), TokenTable::addD5Structures(), TokenTable::addD6Structures(), TokenTable::addDAStructures(), TokenTable::getD4TokensFromStruct(), TokenTable::getDATokensFromStruct(), testStandalone::testConstIterator(), and testStandalone::testNonXml().

typedef SmbiosTableIterator iterator
 

Definition at line 122 of file ISmbios.h.

Referenced by couldBeBayonet(), getIdByteFromOEMItem(), getIdByteFromRevItem(), testPlatform::testConstructionOffset1(), testStandalone::testEachItemAccessors(), testStandalone::testEntryCount(), testStandalone::testGetBoundaries(), testStandalone::testItem_GetBiosInfo(), testStandalone::testItem_GetSystemInfo(), testStandalone::testItemIdentity(), testStandalone::testNonXml(), testPlatform::testOutOfBounds(), testStandalone::testSmbiosXml(), testStandalone::testStreamify(), testStandalone::testSubscriptOperator1(), testStandalone::testSubscriptOperator3(), testStandalone::testTable_Subscript(), testStandalone::testTypeMismatch(), and testPlatform::testVariousAccessors().


Constructor & Destructor Documentation

ISmbiosTable  ) 
 

Definition at line 44 of file SmbiosTable.cpp.

~ISmbiosTable  )  [virtual]
 

Definition at line 47 of file SmbiosTable.cpp.

ISmbiosTable const ISmbiosTable  )  [explicit, private]
 

not implemented (explicitly disallowed)


Member Function Documentation

virtual const_iterator begin  )  const [pure virtual]
 

Standard iterator interface. Points to first table item.

Returns:
iterator or const_iterator Example Iterator Usage:
    smbios::ISmbiosTable *table = smbios::SmbiosFactory::getFactory()->getSingleton();
    smbios::ISmbiosTable::iterator item = table->begin();
    while( item != table->end() )
    {
        cout << "Type of Item: " << item->getType();
        ++item;
    }

Implemented in SmbiosTable.

virtual iterator begin  )  [pure virtual]
 

Standard iterator interface. Points to first table item.

Returns:
iterator or const_iterator Example Iterator Usage:
    smbios::ISmbiosTable *table = smbios::SmbiosFactory::getFactory()->getSingleton();
    smbios::ISmbiosTable::iterator item = table->begin();
    while( item != table->end() )
    {
        cout << "Type of Item: " << item->getType();
        ++item;
    }

Implemented in SmbiosTable.

Referenced by testStandalone::testConstIterator(), testPlatform::testConstructionOffset1(), testStandalone::testEachItemAccessors(), and testStandalone::testEntryCount().

virtual void clearItemCache  )  const [pure virtual]
 

Clears out any cached SmbiosItem entries in the cache.

This API is useful for two instances. First, you can use this to reduce memory usage if you know that you do not need any ISmbiosItem(s) out of the table for a while. The cached ISmbiosItem(s) will be deleted and then re-populated on demand when queries are made for them.

Next, this API is used internally when reReadTable() is called to clear out all old ISmbiosItems.

Warning:
All previous references or pointers to ISmbiosItem objects created from this table become invalid and attempts to access them will cause undefined behaviour (most likely your code will crash.)

Todo:
clearItemCache() needs to be made an abstract function and the definition needs to be moved to the SmbiosItem class. This needs to happen at the same time that itemList is moved.

Implemented in SmbiosTable.

virtual const_iterator end  )  const [pure virtual]
 

Standard iterator interface. Points to one-past-the-last table item.

Used by const_iterator.

Returns:
iterator or const_iterator Example Iterator Usage:
    smbios::ISmbiosTable *table = smbios::SmbiosFactory::getFactory()->getSingleton();
    smbios::ISmbiosTable::iterator item = table->begin();
    while( item != table->end() )
    {
        cout << "Type of Item: " << item->getType();
        ++item;
    }

Implemented in SmbiosTable.

virtual iterator end  )  [pure virtual]
 

Standard iterator interface. Points to one-past-the-last table item.

Returns:
iterator or const_iterator Example Iterator Usage:
    smbios::ISmbiosTable *table = smbios::SmbiosFactory::getFactory()->getSingleton();
    smbios::ISmbiosTable::iterator item = table->begin();
    while( item != table->end() )
    {
        cout << "Type of Item: " << item->getType();
        ++item;
    }

Implemented in SmbiosTable.

Referenced by testStandalone::testConstIterator(), testPlatform::testConstructionOffset1(), testStandalone::testEachItemAccessors(), and testStandalone::testEntryCount().

virtual int getNumberOfEntries  )  const [pure virtual]
 

Returns the number of table items, per SMBIOS table header.

Implemented in SmbiosTable.

Referenced by testStandalone::testConstIterator(), testPlatform::testConstructionOffset1(), and testStandalone::testEntryCount().

virtual smbiosLowlevel::smbios_table_entry_point getTableEPS  )  const [pure virtual]
 

Returns the table entry point structure.

Implemented in SmbiosTable.

void operator= const ISmbiosTable  )  [private]
 

not implemented (explicitly disallowed)

virtual const_iterator operator[] const std::string &   )  const [pure virtual]
 

Standard indexed access by string description. XML ENHANCED.

XML Enhanced indexing operator. You can pass in a string description of the table and the SmbiosTable class will look up the string in an XML description file to find out the item number that corresponds with that text.

The nice extension that is supplied by the XML interface is that all Item access to the item returned are type checked against the XML, so you cannot, for example, access an 8-bit number as a 16-bit number.

The operator[] method returns an iterator that can be used to iterator over all items in the table of the supplied type. So, for example, if you want to perform an operation on all SMBIOS type 0x01 (System Information Block) structures, just index the table object using the [] operator.

Returns:
iterator or const_iterator Sample usage:
// Integer indexing example
smbios::ISmbiosTable *table = smbios::SmbiosFactory::getFactory()->getSingleton();
smbios::ISmbiosTable::iterator item1 = (*table)[0];
cout << "The BIOS Version is: " << item1->getString(0x05) << endl;

// XML string indexing example
smbios::ISmbiosTable *table = smbios::SmbiosXmlFactory::getFactory()->getSingleton();
smbios::ISmbiosTable::iterator item1 = (*table)["BIOS Information"];
cout << "The BIOS Version is: " << item1->getString("BIOS Version") << endl;
See also:
operator[]( const std::string & ) const
See also:
operator[]( const int )

Implemented in SmbiosTable, SmbiosTableXml, and SmbiosTableXml.

virtual iterator operator[] const std::string &   )  [pure virtual]
 

Standard indexed access by string description. XML ENHANCED.

XML Enhanced indexing operator. You can pass in a string description of the table and the SmbiosTable class will look up the string in an XML description file to find out the item number that corresponds with that text.

The nice extension that is supplied by the XML interface is that all Item access to the item returned are type checked against the XML, so you cannot, for example, access an 8-bit number as a 16-bit number.

The operator[] method returns an iterator that can be used to iterator over all items in the table of the supplied type. So, for example, if you want to perform an operation on all SMBIOS type 0x01 (System Information Block) structures, just index the table object using the [] operator.

Returns:
iterator or const_iterator Sample usage:
// Integer indexing example
smbios::ISmbiosTable *table = smbios::SmbiosFactory::getFactory()->getSingleton();
smbios::ISmbiosTable::iterator item1 = (*table)[0];
cout << "The BIOS Version is: " << item1->getString(0x05) << endl;

// XML string indexing example
smbios::ISmbiosTable *table = smbios::SmbiosXmlFactory::getFactory()->getSingleton();
smbios::ISmbiosTable::iterator item1 = (*table)["BIOS Information"];
cout << "The BIOS Version is: " << item1->getString("BIOS Version") << endl;
See also:
operator[]( const std::string & ) const
See also:
operator[]( const int )

Implemented in SmbiosTable, SmbiosTableXml, and SmbiosTableXml.

virtual const_iterator operator[] const  int  )  const [pure virtual]
 

Standard indexed access by integer item type.

The operator[] method returns an iterator that can be used to iterator over all items in the table of the supplied type. So, for example, if you want to perform an operation on all SMBIOS type 0x01 (System Information Block) structures, just index the table object using the [] operator.

Returns:
iterator or const_iterator Sample usage:
// Integer indexing example
smbios::ISmbiosTable *table = smbios::SmbiosFactory::getFactory()->getSingleton();
smbios::ISmbiosTable::iterator item1 = (*table)[0];
cout << "The BIOS Version is: " << item1->getString(0x05) << endl;

// XML string indexing example
smbios::ISmbiosTable *table = smbios::SmbiosXmlFactory::getFactory()->getSingleton();
smbios::ISmbiosTable::iterator item1 = (*table)["BIOS Information"];
cout << "The BIOS Version is: " << item1->getString("BIOS Version") << endl;
See also:
operator[]( const std::string & ) const

Implemented in SmbiosTable.

virtual iterator operator[] const  int  )  [pure virtual]
 

Standard indexed access by integer item type.

The operator[] method returns an iterator that can be used to iterator over all items in the table of the supplied type. So, for example, if you want to perform an operation on all SMBIOS type 0x01 (System Information Block) structures, just index the table object using the [] operator.

Returns:
iterator or const_iterator Sample usage:
// Integer indexing example
smbios::ISmbiosTable *table = smbios::SmbiosFactory::getFactory()->getSingleton();
smbios::ISmbiosTable::iterator item1 = (*table)[0];
cout << "The BIOS Version is: " << item1->getString(0x05) << endl;

// XML string indexing example
smbios::ISmbiosTable *table = smbios::SmbiosXmlFactory::getFactory()->getSingleton();
smbios::ISmbiosTable::iterator item1 = (*table)["BIOS Information"];
cout << "The BIOS Version is: " << item1->getString("BIOS Version") << endl;
See also:
operator[]( const std::string & ) const

Implemented in SmbiosTable.

virtual void rawMode bool  m = true  )  const [pure virtual]
 

Disables all workarounds for _new_ items created by the table.

Any new item generated by the table will not have workarounds applied to them. However, any previously-existing items that have had workarounds applied still exist. If this is not what you want, recommend calling clearItemCache() prior to calling rawMode().

Parameters:
m pass in a bool value to turn raw mode on or off.

Implemented in SmbiosTable.

virtual void reReadTable  )  [pure virtual]
 

Re-Read the table from memory. Invalidates all existing ISmbiosItems.

Not yet implemented This API is intended to be used in the instance where SMBIOS data is not static, ie. BIOS updates SMBIOS information while the system is running.

Most systems have static tables that do not change after the system boots. Systems have been proposed to update this information at runtime inside system SMI calls. This API is put into place to prepare for this possibility.

Warning:
All previous references or pointers to ISmbiosItem objects created from this table become invalid and attempts to access them will cause undefined behaviour (most likely your code will crash.)

Implemented in SmbiosTable.

virtual std::ostream& streamify std::ostream &  cout  )  const [pure virtual]
 

Used by operator << (std::ostream & cout, const ISmbiosTable & ) to.

Users normally would not need or want to call this API. The normal operator<<() has been overloaded to call this function internally.

Implemented in SmbiosTable, SmbiosTableXml, and SmbiosTableXml.

Referenced by smbios::operator<<().


The documentation for this class was generated from the following files:
Generated on Wed Apr 11 16:25:12 2007 for SMBIOS Library by doxygen 1.3.5