/**
 *  Kamefu DESIGN document.
 *  By Michaël Larouche <michael.larouche@kdemail.net>
 *
 *  Latest update: 15 october 2005
 * 
 *  Version 0.2
 *  -Updated Architecture to be closer to current reality.
 *  Version 0.1
 *  -Initial rought draft.
 */
This document present the basic design of Kamefu (KDE All-Machine Emulator Frontend for UNIX) and
his dependencies (kfile_plugins).

Content
-------
1. Application design
2. Architecture

1. Application design
   --------------
The main idea behind Kamefu is to manage a collections of ROMS from various systems. Also to serve as a frontend to differents systems which use differents emulators. Think amaroK but for your ROM collection :)

Which means that Kamefu will be able to:
-Build a collection manager based on ROM kfile_plugins you have installed on your system.
-Display the collection mostly like amaroK does, allow to filter by various criteria like "Editor", "Year", "System" and "Genre".
-Configure system and his emulators directory into Kamefu.
-Handle list of your favorites (so called playlist in a audio/video application)
-A little application like "kfmclient" that take a rom path in input and launch the required emulator for the system.

GUI ideas:
----------
Display of a item:
-Show a title screenshot and a game screenshot
-Show information like the Editorm the Year, Genre and System.
-Able to retrive Wikipedia Entry.
-Has action button like "Launch Game", "Show Meta Information" (using KFileMetaInfoWidget)
Front page:
-Has item like "Select system", "Browse Collection", "Configure Kamefu", "Configure systems."
-Could be used to display "Play game from CDROM", "Play game from ISO image." for Playstation systems.
Collection treeview:
-Ripped(errr based ;) on amaroK Collection sidebar view.
Statictic view:
-Most played item
-Recent additions.

Generic Plugins ideas:
----------------------
-Plugin that advert in Kopete the current game played.


2. Architecture
   ------------
The architecture is loosely based on Kopete architecture.

Services overview:
------------------
-Core library that create singleton manager classes and host the various base classes used in "plugins".
-KFile plugins that retrieve metadata from ROM images.
-RomMetaDataFactory that helps extract metadata depending of the file context(a normal file, a plain ZIP file, a MAME zip file, etc...)
-CollectionAccess is the wrapper around the database. Consult, create and update the database.
-CollectionBuilder that scan folders and retrieve rom meta information.
-GameLauncher is a helper class that launch the correct emulator based on file mimetype.

(FOR A FUTURE RELEASE:) Design problem I have to solve: How to handle differents emulators by system not hardcoded, I don't want to make emulator configuration in C++ neither hardcode the list of emulators by system.

Factory and Manager classes:
--------
-RomMetaDataFactory
-SystemManager

Base classes:
-------------------
-RomMetaData
-System

Helper/Service classess:
-------------------
-GameLauncher
-DatabasePreferences(auto generated by KConfigXT)
-KamefuPreferences(auto generated by KConfigXT)
-CollectionBuilder
-CollectionAccess

Data class:
-----------
-RomMetaInformation (for exchaging data between Collection Builder and Collection access)

Game Launcher class:
----------------------
GameLauncher is a helper class that handle emulator launching. The input is the full path of the ROM image to launch. Then the game launcher determine the system from the rom path and get the right emulator program for the system by reading the configuration.

Collection Builder service:
---------------------------
Collection Builder is the service that list a list of directories defined in a configuration file(directories list must be push to the class). After retriving the metadata, it emit the extracted meta information using RomMetaInformation data class.

For each file, Collection Builder should use a class obtained from RomMetaDataFactory. If no specific class is required, the RomMetaDataFactory will return the DefaultRomMetaData that read the metadata from KFileMetaInfo. This will be useful for exemple for the MAME system to use MAME database to retrive meta information. Also it check if the current file is a ZIP file. the derivate RomMetaData clas will handle the decompression of the zip file. 

1-Before the listing of directories, begin a ROM Transaction. The beginRomTransaction will create a temporary tables that will hold the valid entries.
2-Call the directories listing. It will connect the required signal to CollectionAccess to insert the ROM.
3. While listing a single file(ROM):
FOR EACH ROM
	Check if the ROM is already in database. If yes, retrieve the information and push it into temp table(or cursor). 
	Else get the information from ROM and pust it to temp table.
4. After the listing, call the endRomTransaction. 
endRomTransaction will clean the permanent table and put the content of temporary table into the permanent one.. Then drop the temporary table.


Why RomMetaDataFactory ?
-------------------------
Think first of all at MAME. MAME identify his game from zip files that contain Game data. For exemple windjammers.zip represent the game "WindJammmers" by Data East in 1994 on NeoGeo. MAME use a internal database to get that information. The derived RomMetaData class will retrive in MAME system plugin the meta information from MAME database then push it to the collection builder.

Collection Access service:
--------------------------
Collection Access handle creation, updating and query of the database used by Kamefu. It's currently use the Qt SQL classes and support SQLITE and MYSQL drivers from QtSQL. The intermediate data class use to push and pull rom information is RomMetaInformation.

System plugins
--------------
System plugins represents a game system like a NES, SNES. System plugins mostly offert classes that will be used by core factory classes depending on the context. Context are like collection build and game launching. The system plugins handle what it's specific for each system. Each system plugin will register for mimetypes that the system support. (ex: application/x-rom-snes for SNES system.)
Currently (as version 0.1 of Kamefu), system plugins are very empty.

Why retriving the MD5 hash ?
----------------------------
MD5 hash will be used later to identify good ROMS from a XML database. This will rename ROM image to their good name, get addition information like year, editor, genre.