An eXtensible Car Description format with ATL COM

• Download source code - 1.26 MB

Introduction

How would you select a personal car? There are about 50 major car manufacturers that provide information car-by-car about their models, there are specialized sites too. Would it be time-saving and convenient to have in one file pictures and descriptions of all cars released by a specific manufacturer in a specific year? Say when you are interested in cars released by Honda in the year 2011, you need to download one file only and you can analyze specs on-line or off-line on your platform of choice. This article assumes a positive answer and defines an eXtensible Car Description or XCD format for describing cars in a collection that groups cars by Make (car manufacturer) and Year so that any one file with an extension .CAR has all relative pictures and quick specifications. The article provides an API for browsing CAR files on any platform compatible with Win32. In fact, a set of CAR files representing all car manufacturers is compact in size and easy to browse and analyze on any desktop or mobile platform. Samples of programs that read CAR files are available with the download.

Contents

• Background
• XCD Design Goals
• Used Terminology
• Sample Application
• Object Model
• Initialization With Your Application
• XCD API
• XML Car Description
• Quick XML Description
• Extended XML Description
• Browsing and Analyzing Collections
• Conclusion and License

Background

The collections of car pictures and quick specs grouped by year and make are used in the Car Explorer program that provides an interface to download CAR files for free.

The XCD format elaborates a format that keeps together in one file a set of general images and descriptions. The latter was used in several applications released by MSB LLC from 2005.

XCD Design Goals

The XCD format describes content of CAR files. The design goals for XCD are:

1. One CAR file shall describe all cars for one Make and one Year (excluding submodels in the current version).
2. A valid CAR file shall have pictures and quick specifications for all car models (from XCD v1.1).
3. A valid CAR file shall have at least one car description.
4. Car descriptions are in digest form according to single car description in the XML format.
5. Any CAR file shall provide a unique string identifier within the application that uses it.
6. Within the application scope, any car model in the CAR file shall have a unique string identifier (can be year plus picture title or programmatic).
7. XCD shall support adding, editing, and deleting car pictures and descriptions in a CAR file.
8. Keep valid CAR files small in size, typically less than 1 MB.
9. Acceptance of XCD format at least by one car manufacturer.
10. Free sharing of CAR files.

From goal 1 follows:

1. all cars in any XCD collection are of the same Make and Year, and
2. since Makes are the same, all cars in a collection are of the same Country, not considering scenarios when one Make can be assembled in different countries.

From goal 2 follows:

1. If a model is missing in a collection, the collection is not a valid CAR file.
2. If a picture is missing, or a quick spec is missing or is incomplete for one model in a collection, the collection is not a valid CAR file.

Notice that the phrase “all car models” refers to inclusion into a collection of cars of different models, but not of different trims, colors, not with different engines or optional equipment.

From goals 5 and 6 follows: if identifiers do not follow the design goals, the CAR file is not valid.

In fact, the third design goal is the result of 1 and 2.

Used Terminology

Throughout this article, the terms "CAR file" and "collection" mean the same thing as described in the XCD Design Goals. The words "should", "required", "shall", "optional" are to be interpreted as described in RFC 2119.

Sample Application

The sample applications (MFC, C#, VB) that come with this article are developed with VS 2008 and enable you to read CAR files. Essentially, they have the same visual interface (MFC sample has additional expandable features) and use functions of ATL COM’s library named XCD.dll, which is also developed with VS 2008, to access data in CAR files. Any automation-compatible client can access functions of the XCD library. Build first the XCD_COM project (if XCD.dll is copied - register it with regsvr32, but before registration, you probably need to run Microsoft Visual C++ 2008 SP1 Redistributable Package if your target system does not have Microsoft Visual C++ 2008 installed), and then build the XCD_Client_MFC project that uses the XCD library. You will find in the download the Peugeot_2011.car sample collection, and you can download additional CAR files from the Car Explorer site. Here is the dialog of the XCD_Client_MFC application:

First, click the “Select CAR File” button to select a CAR file from a directory. The Collection area of the dialog shows information about the CAR file as a collection such as collection title, number of images in the collection, collection version. The Car area of the dialog shows information about a particular car in the collection: use spin control to select the next item in the collection. Every car in the collection has an image; click the “Show Picture” button to view the item’s image. Starting from XCD v1.1, each car in a collection is tagged with quick specification details. Select the car detail from the combo box and click the “Get Value” button to see its value. The combo box's item is referred as tag since car technical description can be represented as an XML file (XCD stands also for XML Car Description).

The MFC sample application has additional features. The “Get Data” button located in the expandable bottom area of the dialog shown when you click the “More” button provides an alternative to get all technical information for a car in the collection with a single call. The right expandable area visible with a click on the “Show Legend” button indicates function prototypes used for all related calls in the left area.

Object Model

The XCD library provides methods to read data in CAR files. As shown in the following logical diagram, it is a COM DLL with two objects: Collection and Car.

The Collection object is designed to access information about a collection as a whole. A client application should set the location of a collection with the FFN property, where FFN stands for the Full File Name of the CAR file, before the object's methods can be used. The Collection object is put aside from the Car object as a different entity because of scenarios when an application needs to read only general information about a collection such as its title (string ID), its version strings, or verify if a file is a CAR file.

The methods of the Car object serve to read information about a specific car in a collection such as the car's picture (GetPicture), a particular feature of the car specification (GetValue), or the whole car specification in one call (GetData). Since every Car object method reads the FFN string set in the Collection object, or «uses» the Collection object as shown on the diagram, the Collection object must be created before the Car object. Technically, you can create the Car object without the Collection object, but it would make no sense since there is no way to set the location of a CAR file without the Collection object. This logical bond (composite aggregation) is depicted with the black diamond.

Initialization With Your Application

Any automation-compatible language can use the XCD library to access the methods and properties of its objects. Since the Car object’s methods read the FFN string set in the Collection object, the Collection object must be created before the Car object, as shown:

C++:

' Import description of the XCD library as XCD.tlb from XCD's COM project.
#import "XCD.tlb" no_namespace, raw_interfaces_only

CoInitialize(NULL);

m_pCollection = NULL;
CoCreateInstance(__uuidof(Collection), NULL, CLSCTX_INPROC_SERVER, 
                __uuidof(ICollection), reinterpret_castvoid**>(&m_pCollection));

' Set the location of CAR file.
CComBSTR bstrFFN(
             "C:\\Documents and Settings\\I'm\\My Documents\\Peugeot_2011.car");
m_pCollection->put_FFN(bstrFFN.m_str);

m_pCar = NULL;
CoCreateInstance(__uuidof(Car), NULL, CLSCTX_INPROC_SERVER, 
                             __uuidof(ICar), reinterpret_cast<void** />(&m_pCar));

In the result, the m_pCar pointer is obtained for the Car object’s methods. Notice that the raw_interfaces_only attribute is used with the #import statement to handle the XCD API with relative HRESULTs. If the attribute is dropped, you would get return values directly. For example, instead of:

BSTR bstrCollectionTitle;
HRESULT hr = m_pCollection->GetTitle(&bstrCollectionTitle);

You should write:

BSTR bstrCollectionTitle = m_pCollection->GetTitle();

See the XCD_Client_MFC sample in the download for details.

C#:

Assuming that the reference to the XCD library is set in the project settings, the references to its objects are obtained as follows:

private XCD.Collection objCollection;
private XCD.Car objCar;

objCollection = new XCD.Collection();

' Set the location of CAR file.
objCollection.FFN = 
         "C:\\Documents and Settings\\I'm\\My Documents\\Peugeot_2011.car";

objCar =  new XCD.Car();

See the XCD_Client_CS sample for details.

VB:

Assuming that the reference to the XCD library is set in the project settings, the references to its objects are obtained as follows:

Dim objCollection As XCD.Collection ' enables IntelliSense
Dim objCar As XCD.Car ' enables IntelliSense

objCollection = New XCD.Collection

' Set the location of CAR file.
objCollection.FFN = 
    "C:\\Documents and Settings\\I'm\\My Documents\\Peugeot_2011.car"

objCar = New XCD.Car

Notice that a reference to an object in VB can be created in several ways, and it could also be created like:

Dim objCollection As Object
objCollection = CreateObject("XCD.Collection")

or

Dim objCollection = New XCD.Collection

However, if you want to see IntelliSence context help as you type, you should use the first method, called early binding. See the XCD_Client_VB sample for details.

XCD API

The following table enumerates the methods and properties implemented in XCD. For strings, the BSTR type is used to enable the use of XCD with languages other than C++. In other words, XCD is automation-enabled. All methods return an HRESULT value as COM's default return type. Notice that the quick specs are available since v1.1 of XCD; if GetXCDVersion returns an empty string (this means v1.0 of XCD), only car pictures and titles are available.

Object	Function Prototype	Description
Collection	put_FFN(BSTR bstrFFN /* in */)	Sets the Full File Name of the CAR file to read.
	GetTitle(BSTR* pbstrTitle /* out */)	Reads the title of the collection.
	GetCount(USHORT pnCount /* out */)	Reads the number of items (cars) in the collection.
	GetVersion(BSTR* bstrCollectionVersion /* out */)	Reads the version of the collection.
	GetXCDVersion(BSTR* pbstrXCDVersion /* out */)	Reads the version of the XCD format.
	IsCarFile(VARIANT_BOOL* pbCarFile /* out */)	Verifies if the collection is a CAR file.
Car	GetPictureTitle(USHORT nItem /* in */, BSTR* pbstrTitle /* out */)	Reads the picture title for the nItem car in the collection.
	GetPicture(USHORT nItem /* in */, IPicture** ppPicture /* out */)	Returns the address of the pointer variable that receives the IPicture interface pointer for the nItem car in the collection, where IPicture is the standard COM interface that makes it possible to get information about a picture (get_Width, get_Height) and draw the picture on a specified device context (Render).
	GetValue(USHORT nItem /* in */, BSTR bstrTag /* in */, BSTR* pbstrValue /* out */)	Reads the value of the specified tag (bstrTag) in the car specification for the nItem car in the collection. The possible names for bstrTag are: Year, Make, Model, Submodel, Type, Price, Country, Length, Width, Height, Weight, Power, Fuel, Clearance, Tank Volume. This function has a disadvantage that in order to read all data for a car, you need to make more than 10 calls with different bstrTag names. In order to get the whole specification with one call, use GetData instead.
	GetData(USHORT nItem /* in */, VARIANT* pData /* out */)	Returns a pointer to the VARIANT structure that contains a SAFEARRAY of data representing the quick specification of the nItem car in the collection.

XML Car Description

A car description can be represented in XML form. The XCD format describes cars in two forms.

Quick XML Description

The first form takes a quick technical specification of a car and puts it into XML according to the following table as of XCD version 1.1:

Section	Tag	Description
Summary	Year	Specifies the year in which the car was manufactured.
	Make	Specifies the car maker (manufacturer).
	Model	Specifies the model of the car.
	SubModel	Specifies the submodel of the car, often referred as trim.
	Type	Specifies the body type of the car such as Sedan, Coupe, Convertible, SUV etc.
	Price	Specifies the MSRP price of the car in US dollars, where MSRP is the Manufacturer's Suggested Retail Price.
	Country	Specifies the main country where the car is manufactured.
Measures	Length	Specifies the length of the car in inches.
	Width	Specifies the width of the car (mirrors folded) in inches.
	Height	Specifies the height of the car in inches.
	Weight	Specifies the curb weight of the car in pounds.
Engine	Power	Specifies the engine's horsepower.
	Fuel	Specifies the type of fuel used by the engine such as gas, diesel etc.
Misc	Clearance	Specifies the ground clearance of the car, which is the distance between the lowest point on the car and the road.
	Tank_Volume	Specifies the tank volume of the car in gallons.

Extended XML Description

The second form of XCD extends the XML description of a single car with the first form and describes all cars in a collection in the extended XML form:

<?xml version="1.0" encoding="Windows-1252"?>
<XCD>
<Collection>
  <Title>Peugeot 2011</Title>
  <Version>1.0</Version>
  <XCD_Version>1.1</XCD_Version>
</Collection>

<Car id="2011_Peugeot_207_CC">
<Summary>
  <Year>2011</Year>
  <Make>Peugeot</Make>
  <Model>207 CC</Model>
  <SubModel>Sport</SubModel>
  <Type>Convertible</Type>
  <Price>$27,678</Price>
  <Country>France</Country>
</Summary>

<Measures>
  <Length>159.20</Length>
  <Width>68.90</Width>
  <Height>55.00</Height>
  <Weight>2,959</Weight>
</Measures>

<Engine>
  <Power>120</Power>
  <Fuel>Gas</Fuel>
</Engine>

<Miscellaneous>
  <Clearance>No data</Clearance>
  <Tank_Volume>13.21</Tank_Volume>
</Miscellaneous>
</Car>

<Car id="2011_Peugeot_NextModel">
<!-- Next car in the collection -->
</Car>
</XCD>

In this way, XCD describes a collection (CAR file) in its header area between the tags <Collection></Collection> and enumerates all cars in the collection in its main area according to the first form of XCD. In addition, a car’s picture title (plus year) serves as string ID of a car within the XCD document, like <Car id="2011_Peugeot_207_CC">. You can see samples of XCD documents in both forms in the download.

Browsing and Analyzing Collections

What applications can be used to open and read CAR files? First, from a programmer's perspective, you can use the samples provided in the download, and tailor them as you wish according to the XCD description in this article. Second, as a user, you can use the Car Explorer program, which has more elaborated interfaces making it possible to compare and analyze cars from different collections, and also provides an interface to download CAR files for free. Can you edit or create CAR files? Yes, the MSB Wizard (versions are available for Windows 7, Vista, Windows XP) enables you to do that (just rename the CAR extension to MSS before editing, and rename it back to CAR to view with Car Explorer).

Conclusion and License

Some things take more prudence than the others. This is certainly about cars, especially at the point of making a decision. However, how does one select her or his favorite car? What options he or she has? Assuming that all basic information about all cars released by a car manufacturer in a certain year is kept in one file according to a uniform format and is easily accessible, you simply download one file to analyze and decide when you are interested in a certain Make of a specific Year. What can be more simple?

In this article, the specification for XCD format was described that facilitates answers on these questions. The XCD description and the code provided as download with this article are licensed under the Creative Commons License that includes option to build upon this work both non-commercially and commercially on the condition that you Attribute this work:

The CAR files or collections as described in this article are supposed to be shared freely, and selling them would be contrary to the terms.