- renamed PLUGIN_getSupportedGames to PLUGIN_gameIDList for consistency

- renamed Engine_XXX_gameList to Engine_XXX_gameList for consistency
- added new Engine_XXX_findGameID / PLUGIN_findGameID function
- updated plugins code to take advantage of the new plugin API, to support
  obsolete gameids w/o showing them to the user

svn-id: r20752

2 files changed, 63 insertions, 35 deletions

diff --git a/base/plugins.cpp b/base/plugins.cpp
index 4a9201c79e..01d9e58abb 100644
--- a/base/plugins.cpp
+++ b/base/plugins.cpp
@@ -32,6 +32,7 @@
 typedef Engine *(*EngineFactory)(GameDetector *detector, OSystem *syst);
 
 typedef const char *(*NameFunc)();
+typedef GameSettings (*GameIDQueryFunc)(const char *gameid);
 typedef GameList (*GameIDListFunc)();
 typedef DetectedGameList (*DetectFunc)(const FSList &fslist);
 
@@ -60,8 +61,8 @@ typedef DetectedGameList (*DetectFunc)(const FSList &fslist);
 
 #else
 
-PluginRegistrator::PluginRegistrator(const char *name, GameList games, EngineFactory ef, DetectFunc df)
-	: _name(name), _ef(ef), _df(df), _games(games) {
+PluginRegistrator::PluginRegistrator(const char *name, GameList games, GameIDQueryFunc qf, EngineFactory ef, DetectFunc df)
+	: _name(name), _qf(qf), _ef(ef), _df(df), _games(games) {
 	//printf("Automatically registered plugin '%s'\n", name);
 }
 
@@ -70,28 +71,13 @@ PluginRegistrator::PluginRegistrator(const char *name, GameList games, EngineFac
 
 #pragma mark -
 
-GameSettings Plugin::findGame(const char *gameName) const {
-	// Find the GameSettings for this game
-	assert(gameName);
-	GameList games = getSupportedGames();
-	GameSettings result = {NULL, NULL};
-	for (GameList::iterator g = games.begin(); g != games.end(); ++g) {
-		if (!scumm_stricmp(g->gameid, gameName)) {
-			result = *g;
-			break;
-		}
-	}
-	return result;
-}
-
-#pragma mark -
-
 #ifndef DYNAMIC_MODULES
 class StaticPlugin : public Plugin {
 	PluginRegistrator *_plugin;
 public:
 	StaticPlugin(PluginRegistrator *plugin)
 		: _plugin(plugin) {
+		assert(_plugin);
 	}
 	
 	~StaticPlugin() {
@@ -101,11 +87,19 @@ public:
 	const char *getName() const { return _plugin->_name; }
 
 	Engine *createInstance(GameDetector *detector, OSystem *syst) const {
+		assert(_plugin->_ef);
 		return (*_plugin->_ef)(detector, syst);
 	}
 
 	GameList getSupportedGames() const { return _plugin->_games; }
+
+	GameSettings findGame(const char *gameid) const {
+		assert(_plugin->_qf);
+		return (*_plugin->_qf)(gameid);
+	}
+
 	DetectedGameList detectGames(const FSList &fslist) const {
+		assert(_plugin->_df);
 		return (*_plugin->_df)(fslist);
 	}
 };
@@ -120,6 +114,7 @@ class DynamicPlugin : public Plugin {
 	Common::String _filename;
 
 	Common::String _name;
+	GameIDQueryFunc _qf;
 	EngineFactory _ef;
 	DetectFunc _df;
 	GameList _games;
@@ -128,7 +123,7 @@ class DynamicPlugin : public Plugin {
 
 public:
 	DynamicPlugin(const Common::String &filename)
-		: _dlHandle(0), _filename(filename), _ef(0), _df(0), _games() {}
+		: _dlHandle(0), _filename(filename), _qf(0), _ef(0), _df(0), _games() {}
 
 	const char *getName() const					{ return _name.c_str(); }
 
@@ -138,6 +133,12 @@ public:
 	}
 
 	GameList getSupportedGames() const { return _games; }
+
+	GameSettings findGame(const char *gameid) const {
+		assert(_qf);
+		return (*_qf)(gameid);
+	}
+
 	DetectedGameList detectGames(const FSList &fslist) const {
 		assert(_df);
 		return (*_df)(fslist);
@@ -196,13 +197,20 @@ bool DynamicPlugin::loadPlugin() {
 	_name = nameFunc();
 
 	// Query the plugin for the game ids it supports
-	GameIDListFunc gameListFunc = (GameIDListFunc)findSymbol("PLUGIN_getSupportedGames");
+	GameIDListFunc gameListFunc = (GameIDListFunc)findSymbol("PLUGIN_gameIDList");
 	if (!gameListFunc) {
 		unloadPlugin();
 		return false;
 	}
 	_games = gameListFunc();
 
+	// Retrieve the gameid query function
+	_qf = (GameIDQueryFunc)findSymbol("PLUGIN_findGameID");
+	if (!_qf) {
+		unloadPlugin();
+		return false;
+	}
+
 	// Retrieve the factory function
 	_ef = (EngineFactory)findSymbol("PLUGIN_createEngine");
 	if (!_ef) {
@@ -225,23 +233,18 @@ bool DynamicPlugin::loadPlugin() {
 }
 
 void DynamicPlugin::unloadPlugin() {
-#if defined(UNIX) || defined(__DC__)
 	if (_dlHandle) {
+#if defined(UNIX) || defined(__DC__)
 		if (dlclose(_dlHandle) != 0)
 			warning("Failed unloading plugin '%s' (%s)", _filename.c_str(), dlerror());
-	}
-}
-#else
-#if defined(_WIN32)
-	if (_dlHandle) {
+#elif defined(_WIN32)
 		if (!FreeLibrary((HMODULE)_dlHandle))
 			warning("Failed unloading plugin '%s'", _filename.c_str());
-	}
-}
 #else
 #error TODO
 #endif
-#endif
+	}
+}
 
 #endif	// DYNAMIC_MODULES
 
diff --git a/base/plugins.h b/base/plugins.h
index 311725581d..2d778e2a51 100644
--- a/base/plugins.h
+++ b/base/plugins.h
@@ -41,14 +41,16 @@ typedef Common::Array<GameSettings> GameList;
  * A detected game. Carries the GameSettings, but also (optionally)
  * information about the language and platform of the detected game.
  */
-struct DetectedGame : GameSettings {
+struct DetectedGame {
+	const char *gameid;
+	const char *description;
 	Common::Language language;
 	Common::Platform platform;
 	DetectedGame() : language(Common::UNK_LANG), platform(Common::kPlatformUnknown) {}
 	DetectedGame(const GameSettings &game,
 	             Common::Language l = Common::UNK_LANG,
 	             Common::Platform p = Common::kPlatformUnknown)
-		: GameSettings(game), language(l), platform(p) {}
+		: gameid(game.gameid), description(game.description), language(l), platform(p) {}
 };
 
 /** List of detected games. */
@@ -71,7 +73,7 @@ public:
 	virtual int getVersion() const	{ return 0; }	// TODO!
 
 	virtual GameList getSupportedGames() const = 0;
-	virtual GameSettings findGame(const char *gameName) const;
+	virtual GameSettings findGame(const char *gameid) const = 0;
 	virtual DetectedGameList detectGames(const FSList &fslist) const = 0;
 
 	virtual Engine *createInstance(GameDetector *detector, OSystem *syst) const = 0;
@@ -84,6 +86,21 @@ public:
  * makes it possible to compile the very same code in a module
  * both as a static and a dynamic plugin.
  *
+ * Each plugin has to define the following functions:
+ * - GameList Engine_##ID##_gameIDList()
+ *   -> returns a list of gameid/desc pairs. Only used to implement '--list-games'.
+ * - GameSettings Engine_##ID##_findGameID(const char *gameid)
+ *   -> asks the Engine for a GameSettings matching the gameid. If that is not
+ *      possible, the engine MUST set the gameid of the returned value to 0.
+ *      Note: This MUST succeed for every gameID on the list returned by
+ *      gameIDList(), but MAY also work for additional gameids (e.g. to support
+ *      obsolete targets).
+ * - DetectedGameList Engine_##ID##_detectGames(const FSList &fslist)
+ *   -> scans through the given file list (usually the contents of a directory),
+ *      and attempts to detects games present in that location.
+ * - Engine *Engine_##ID##_create(GameDetector *detector, OSystem *syst)
+ *   -> factory function, create an instance of the Engine class.
+ *
  * @todo	add some means to query the plugin API version etc.
  */
 
@@ -91,13 +108,19 @@ public:
 #define REGISTER_PLUGIN(ID,name) \
 	PluginRegistrator *g_##ID##_PluginReg; \
 	void g_##ID##_PluginReg_alloc() { \
-		g_##ID##_PluginReg = new PluginRegistrator(name, Engine_##ID##_gameList(), Engine_##ID##_create, Engine_##ID##_detectGames);\
+		g_##ID##_PluginReg = new PluginRegistrator(name, \
+			Engine_##ID##_gameIDList(), \
+			Engine_##ID##_findGameID, \
+			Engine_##ID##_create, \
+			Engine_##ID##_detectGames \
+			);\
 	}
 #else
 #define REGISTER_PLUGIN(ID,name) \
 	extern "C" { \
 		PLUGIN_EXPORT const char *PLUGIN_name() { return name; } \
-		PLUGIN_EXPORT GameList PLUGIN_getSupportedGames() { return Engine_##ID##_gameList(); } \
+		PLUGIN_EXPORT GameList PLUGIN_gameIDList() { return Engine_##ID##_gameIDList(); } \
+		PLUGIN_EXPORT GameSettings PLUGIN_findGameID(const char *gameid) { return Engine_##ID##_findGameID(gameid); } \
 		PLUGIN_EXPORT Engine *PLUGIN_createEngine(GameDetector *detector, OSystem *syst) { return Engine_##ID##_create(detector, syst); } \
 		PLUGIN_EXPORT DetectedGameList PLUGIN_detectGames(const FSList &fslist) { return Engine_##ID##_detectGames(fslist); } \
 	}
@@ -111,17 +134,19 @@ public:
 class PluginRegistrator {
 	friend class StaticPlugin;
 public:
+	typedef GameSettings (*GameIDQueryFunc)(const char *gameid);
 	typedef Engine *(*EngineFactory)(GameDetector *detector, OSystem *syst);
 	typedef DetectedGameList (*DetectFunc)(const FSList &fslist);
 
 protected:
 	const char *_name;
+	GameIDQueryFunc _qf;
 	EngineFactory _ef;
 	DetectFunc _df;
 	GameList _games;
 
 public:
-	PluginRegistrator(const char *name, GameList games, EngineFactory ef, DetectFunc df);
+	PluginRegistrator(const char *name, GameList games, GameIDQueryFunc qf, EngineFactory ef, DetectFunc df);
 };
 #endif