===========================================================================
CatShanty2 用 リネームデータ拝借プラグインについて
===========================================================================
色々出回っている ROM イメージのリネームデータを利用して、CatShanty2 のライブ
ラリ情報を更新してしまおうという野望のための、橋渡しをするプラグインの仕様書
です。

リストデータは多種多様の様式で記述されているので、それぞれのリストデータ用の
プラグインを作って対応しようという魂胆です。


===========================================================================
本体とプラグインの動作
===========================================================================
リストデータは CatShanty2 側でメモリに読み込んであります。(※１）
プラグインへは、リストデータの開始ポインタと、検索のキーとなる文字列（16進数
のCRC値、またはファイル名）のポインタを渡します。（※２）

基本的にプラグイン側では、GetTitle() などの命令毎に、要求された情報をキーを
元に探し出し、用意されたバッファ（のポインタ）へ情報を格納して終了します。
見つからない場合はヌルを格納します。


===========================================================================
リストデータについて（※１）
===========================================================================
リストデータは CatShanty2の「テスト」又は「実行」ボタンがクリックされた時に
指定されたリストデータファイルをメモリに展開しています。

プラグインへは展開先の開始ポインタを都度渡していますので、そこを参照して頂け
れば、常に新しいリストデータを参照できます。

例えばユーザーがリストファイルを変更したさいでも、特別な処理をすること無く、
新しいリストデータがメモリに読み込まれた状態になっています。


===========================================================================
キーのCRC値について（※２）
===========================================================================
CatShanty2では、先人の素晴らしい知恵と恩恵に預かり、CRC/CRC32値を利用させて
頂いています。こういった先人のツールが無ければ CatShanty2の完成は有り得ませ
んでした。大変感謝しています。

さて、ZIP系のDLLなどには、CRC32値をリクエストしたとき、先頭が 0 の場合、0 を
省略して返してくれるものが存在します。

これは値として間違いでもバグでもなく、数値上全く問題のないHEX値であり、0 が省
略されるのは「仕様」であると理解しています。

CatShanty2では、受け取った値を補正すること無くデータベースへ格納し、必要があ
れば補正を行っています。

プラグインへは、データベースの値をそのまま渡していますので、中には先頭の 0 が
省略されたものもあるかも知れません。

CatShanty2側からは、プラグイン作者様が対象にしているリストデータや、行なおう
としている検索処理の方法などを予想することはできません。

先頭の 0 が省略されたケースが世の中に存在することを理解していただき、作者様が
処理上必要である場合には不足した 0 を補正するなどし、プラグインを制作して頂け
れば幸いです。


===========================================================================
変更履歴
===========================================================================
2013/01/01	検索元キーに「CRC」に加え「ファイル名」も扱えるよう拡張。
			GetXXXXXX 系にて、iKEYbit（旧iCRCbit）を仕様変更。
			あと、以前指摘されたような気がするLPTSTR→LPSTR表記を修正。
2010/07/02	第一版


===========================================================================
関数一覧
===========================================================================
GetPluginVersion	プラグインバージョンの取得
GetPluginAuthor		プラグイン作者情報の取得
GetPluginInfo		プラグイン情報の取得

GetTitle			タイトル名の取得
GetMaker			メーカー名の取得
GetCountry			国記号の取得
GetVersion			ROMバージョンの取得
GetGenre			ジャンルの取得
GetYear				発売年の取得（YYYY）
GetImgNum			ROMナンバーの取得
GetR				R指定の取得
GetCreator			ゲームクリエイター情報の取得
GetMemo				ゲームに関するメモの取得

GetKana				読み仮名の取得
GetDeveloper		開発元の取得
GetSaleDate			発売年月日の取得（YYYY or YYYY-mm or YYYY-mm-dd）
GetModel			型番の取得
GetPrice			価格の取得
GetMediaInfo		メディア情報の取得
GetDeviceInfo		対応機器の取得
GetPlayer			プレイヤー数の取得
GetSaveInfo			セーブデータ情報の取得
GetSoundInfo		サウンド情報の取得
GetCeroRating		拡張R指定の取得


リストデータによっては用意されていない情報もあります。
その場合は関数を実装しなければ本体側でそのように処理します。




===========================================================================
プラグイン自体に関するAPI
===========================================================================


---------------------------------------------------------------------------
int WINAPI	GetPluginVersion(
				)
---------------------------------------------------------------------------
機能
		プラグインバージョンの取得。
引数
		なし
戻り値
		バージョン番号に100をかけた数値が返る。




---------------------------------------------------------------------------
int WINAPI	GetPluginAuthor(
				LPSTR		&lpszAuthor
				int			iSize
			)
---------------------------------------------------------------------------
機能
		プラグイン作者情報の取得。
引数
		lpszAuthor
			作者情報（改行無し）格納先バッファのポインタ。
			iSize分の確保が保証されている。
		iSize
			バッファサイズ指定。（終端のヌル含む）
			これを超える場合、この値まで格納する。
			また、0 が指定された場合は必要なバッファサイズを返す。
戻り値
		エラー値または必要なバッファサイズ。




---------------------------------------------------------------------------
int WINAPI	GetPluginInfo(
				LPSTR		&lpszInfo
				int			iSize
			)
---------------------------------------------------------------------------
機能
		プラグイン情報の取得。
引数
		lpszInfo
			プラグイン情報（改行無し）格納先バッファのポインタ。
			iSize分の確保が保証されている。
		iSize
			バッファサイズ指定。（終端のヌル含む）
			これを超える場合、この値まで格納する。
			また、0 が指定された場合は必要なバッファサイズを返す。
戻り値
		エラー値または必要なバッファサイズ。




===========================================================================
リストデータから情報を取得するAPI
===========================================================================


---------------------------------------------------------------------------
int WINAPI	GetXXXXXX(		# XXXXXX には Title や Maker などが該当。
				LPCTSTR		lpszListData
				LPCTSTR		lpszKEY
				int			iKEYbit
				LPSTR		&lpszBuffer
				int			iSize
			)
---------------------------------------------------------------------------
※ 文字列を取得する以下７つのAPIは全て同じ書式です。
		GetTitle		タイトル
		GetMaker		メーカー
		GetCountry		国
		GetVersion		バージョン
		GetGenre		ジャンル
		GetCreator		クリエイター
		GetMemo			メモ
		GetKana			読み仮名
		GetDeveloper	開発元
		GetSaleDate		発売年月日（YYYY or YYYY-mm or YYYY-mm-dd）
		GetModel		型番
		GetPrice		価格
		GetMediaInfo	メディア情報
		GetDeviceInfo	対応機器
		GetPlayer		プレイヤー数
		GetSaveInfo		セーブデータ情報
		GetSoundInfo	サウンド情報
		GetCeroRating	拡張R指定

機能
		文字列情報の取得。
引数
		lpszListData
			リストデータの格納されているポインタ。
			内容は書き換えないで下さい。ロックされています。
		lpszKEY
			検索するキーの文字列が格納されているポインタ。
			「CRC（16進数表記）」または「ファイル名」がやってきます。
			内容は書き換えないで下さい。ロックされています。
		iKEYbit
			キーがCRC値の場合、 32bit か 16bit かを示しています。
			0 or 32 で 32bit を示します。
			16      で 16bit を示します。
			キーがファイル名の場合、拡張子の有無を示しています。
			100 で ファイル名本体のみ ("hoge"形式    ) を示しています。
			101 で ファイル名＋拡張子 ("hoge.zip"形式) を示しています。
		lpszBuffer
			情報格納先バッファのポインタ。
			iSize分の確保が保証されている。
		iSize
			バッファサイズ指定。（終端のヌル含む）
			これを超える場合、この値まで格納する。
			また、0 が指定された場合は必要なバッファサイズを返す。
戻り値
		エラー値または必要なバッファサイズ。


 ※ GetSaleDate について

 		発売年月日は以下の形式で格納してください。

		発売年月日が取得可能であれば YYYY-mm-dd 形式
		発売年月　が取得可能であれば YYYY-mm    形式
		発売年　　が取得可能であれば YYYY       形式




---------------------------------------------------------------------------
int WINAPI	GetXXXXXX(		# XXXXXX には Year , ImgNum , R  が該当。
				LPCTSTR		lpszListData
				LPCTSTR		lpszKEY
				int			iKEYbit
			)
---------------------------------------------------------------------------
※ 数値を取得する以下３つのAPIは全て同じ書式です。
		GetYear		発売年
		GetImgNum	イメージナンバー
		GetR		R指定
機能
		数値情報の取得。
引数
		lpszListData
			リストデータの格納されているポインタ。
			内容は書き換えないで下さい。ロックされています。
		lpszKEY
			検索するキーの文字列が格納されているポインタ。
			「CRC（16進数表記）」または「ファイル名」がやってきます。
			内容は書き換えないで下さい。ロックされています。
		iKEYbit
			キーがCRC値の場合、 32bit か 16bit かを示しています。
			0 or 32 で 32bit を示します。
			16      で 16bit を示します。
			キーがファイル名の場合、拡張子の有無を示しています。
			100 で ファイル名本体のみ ("hoge"形式    ) を示しています。
			101 で ファイル名＋拡張子 ("hoge.zip"形式) を示しています。
戻り値
		エラー値または結果数値。
			発売年				4ケタ数値
			イメージナンバー	ROM番号数値
			R指定				0=なし, 1=あり




===========================================================================
エラー値について
===========================================================================
以下の値のマイナス値（-1をかけた数値）がそれぞれのエラー値です。

&H200	'512	リストファイル中に指定されたキーが無い
&H201	'513	利用できないリストっぽい
&H300	'768	正しく取得したが該当データは不在だった（ヌルだった等）
&H301	'769	正しく取得したが数値ではなかった（戻り値が数値のもの用）




===========================================================================
書いた人：hey_kitarou
配 布 元：http://www.catshanty.com/
===========================================================================
