------------------------------------------------------------------------------
HSPTVAPP ver0.9 REFERENCE MANUAL                    HSP : Hot Soup Processor  
ＨＳＰ拡張拡張DLLリファレンス         copyright 2005-2013 (c) onion software  
------------------------------------------------------------------------------

・はじめに

	このDLLは、Hot Soup Processor ver3以降とともに使用することで、
	HSPTVAPPのネットワークサービスにアクセスする機能を提供します。
	HSPTVAPPにより、HSPで作成したプログラムにネットランキング機能を手軽に追加することができます。
	また、サーバー上のデータを更新する機能によりアイデア次第で様々な用途に使用することが可能です。
	HSPTVAPPは、無償で利用可能です。

	HSPTVAPPでできること

	・HSPで作成したプログラムにネット集計ハイスコアランキングを追加できます
	・ランキングにはユーザー名、コメントなどを付加することができます
	・HSPTVブラウザ上のランキング作成と同じ命令、同じ方法で利用可能です
	・HSPTVブラウザで配信されているプログラムを実行形式にして配布することができます
	　(HSPTVブラウザとランキングを共有できます)

	HSPTVAPPは、スコアなどのランキングを管理し、ネット上で共有するためのシステムです。
	情報の更新は即時に行なわれますが、あくまでも非同期のデータ共有を想定したもので、
	リアルタイムの更新には向いていません。


・使い方の概要

	HSPTVAPP対応プログラムのテストには、スクリプトの先頭に以下の行を追加
	してください。

		#include "hsptvapp.as"

	これで、HSPTVAPPの動作チェックと、ランキング機能が利用できるようになります。
	ランキング機能に関する命令は、HSPTVブラウザ用のスクリプトで使用する命令群と
	互換性があります。

	HSPTVAPPは、HSPTVブラウザのランキング対応と同様のプロセスでプログラムの作成、
	テストが可能です。最初は、ローカル(ネットワークに接続しない状態)のテストで確認した上で、
	ネットワークへの接続を行なってください。


・スタートアップコードの取得

	実際にネットワーク接続を行ないHSPTVAPPを利用する場合は、スタートアップコードと呼ばれる
	識別用の文字列が必要になります。スタートアップコードにより、正規のユーザーであることを識別します。

	スタートアップコードは、SoupSeedサイト上で取得することができます。
	(現在のβバージョンでは、HSPプログラムコンテスト2012に登録されている作品とリンクされた
	スタートアップコードだけが取得できます。正式サービス時には、新規のプログラム登録と、
	スタートアップコードの発行を受け付ける予定です。)

		SoupSeedサイト
		http://dev.onionsoft.net/seed/

	HSPTVAPP ID及びスタートアップコードは、SoupSeedのユーザーメニューで、登録されている
	プログラム(作品)ごとに用意されている「HSPTVAPP用ID取得」のボタンを押すことで表示されます。
	個別のプログラムごとに用意されたスタートアップコードを、スクリプトの開始直後にhsptv_start命令の
	パラメーターとして指定することで、ネット接続が有効になります。

		hsptv_start "スタートアップコード"

	hsptv_start命令を使用しないか、または空の文字列("")が指定された場合は、ローカル
	(ネットワークに接続しない状態)のテストモードになります。この場合は、hsptvapp.dllと同じフォルダに
	ランキングを保存するための「hsptvdat.txt」ファイルが作られて、サーバーに接続した場合と
	同じように動作します。
	hsptv_start命令により、ネット接続が有効になった場合は、それ以降はHSPTV!サーバー上の
	ランキングデータが参照されます。
	また、ユーザー情報として設定されているPROXY(代理)サーバーも有効になります。


・ランキング機能について

	HSPTVAPPの機能により、ランキング情報を保持することができます。
	これは、動作しているソフトに対して「スコア」「ユーザー名」「コメント」等の情報を
	一定量保存しておくもので、ゲームのハイスコア情報などを記録するなど様々な用途に使用できます。

	ランキング機能で保存される情報は、以下の通りです。

		■スコア

			32bitの整数値。マイナス値は扱えません。
			スコアの値が大きい順に上位30位が保持されます。

		■ユーザー名 

			スコアに付随するデータです。
			スコアを登録したユーザー名の情報を文字列で保持します。
			ユーザー名は、HSPTVブラウザのオプションで設定された
			名前が自動的に使用されます。(英文字のみ20字まで)

		■コメント

			スコアに付随するデータです。
			スコアを登録したユーザーのコメント(付加情報)を
			文字列で保持します。
			この項目は、登録時のコメントに利用するだけでなく、
			ソフトに関する情報を付加するなどプログラム側で自由に
			利用することが可能です。
			コメントには最大255文字までの文字列を保持できます。

	実際に、HSPTVサーバーにプログラムが登録され、HSPTVブラウザにネットから
	配信された場合には、スコア情報はサーバーに保持され、ユーザーの情報を
	記録するインターネットランキングとして機能します。

	HSPTV対応プログラム作成のためにテストしている状態(スクリプトエディタ
	から実行している時)では、カレントディレクトリにスコア情報を保持する
	ためのローカルファイル(hsptvdat.txt)が作成され、サーバーに登録される
	時と同じ状態をシミュレートします。
	(テストの段階では、HSPTVサーバーに情報は送信されません。)

	ユーザーが作成したプログラムでは、「スコア」「ユーザー名」「コメント」
	の情報を自由に取得、更新することができます。
	ハイスコアの保持に使用することはもちろん可能ですし、他の情報を保持
	するために応用することもできます。
	サーバーでは、スコアの値が大きい順に最大３０件までデータを記録して
	いますが、プログラム側が何件まで表示するか、どの項目を表示するか、
	またスコアの値を決める方法も任されています。

	ランキング機能を利用するプログラムを作成する場合には、このドキュメント
	に記載されている「サーバー送信について」の項目をお読み頂き、同意された
	上で開始してください。


・ユーザー情報について

	HSPTVAPPを使用する際のユーザー設定項目がいくつか用意されています。

		■名前(最大20文字)

		ランキングの登録時に使用されるユーザーの名前です。
		スペースを含まない英文字のみで、最大20文字まで設定できます。

		■ユーザーキー(最大32文字)

		正規のユーザーを識別するための暗号化された文字列となります。
		この項目は現在使われていません。将来の拡張で使用される予定です。

		■PROXYアドレス(最大63文字)

		通信を行なう際にPROXY(代理)サーバーを使う場合のアドレスを指定します。
		特に必要のない場合は、空の文字列にしておいてください。

		■PROXYポート(最大63文字)

		通信を行なう際にPROXY(代理)サーバーを使う場合のポート番号を指定します。
		特に必要のない場合は、空の文字列にしておいてください。

	これらは、HSPTVブラウザでユーザーが設定する項目と同一です。
	HSPTVAPPでは、独立したプログラムとなるため、ユーザー設定項目を編集する
	機能を独自に実装する必要があります。
	サンプルプログラム(hsptv_test.hsp)では、簡単なユーザー設定編集の画面が
	用意されていますので、参考にしてみてください。

	ユーザー情報は、dllのあるフォルダに設定ファイルとして「hsptvapp.ini」を
	用意して保存しておくことが可能です。設定ファイルは、拡張命令により手軽に
	アクセスすることが可能です。


・命令リファレンス

	「hsptvapp.as」を利用することで、以下の命令を新規に使用できるように
	なります。

	hsptv_start "code"				HSPTVAPP通信の開始

		"code" : スタートアップコード文字列

		HSPTVAPPによるサーバーとの通信を開始します。
		"code"にスタートアップコードと呼ばれる文字列を指定する必要があります。
		スタートアップコードは、SoupSeedサイトにてプログラムの作者だけに
		発行されるパスワードのようなものです。
		スタートアップコードが正しく認識されると、以降はHSPTV!サーバーから
		ランキング情報を取得することができるようになります。
		hsptv_start命令に空の文字列("")を指定するか、またはhsptv_start命令を
		実行しなかった場合は、ローカルテストモードとなり、サーバーとの通信を
		せずにスクリプトを実行中のマシン上でテストが行なわれます。


	hsptv_up p1,"comment", p2			ランキングデータ更新

		p1 : スコア値(32bit整数値)
		"comment" : コメント文字列(256byteまで)
		p2 : オプション機能値

		ランキングデータを更新します。
		スコア,コメント情報を反映させます。
		スコアがマイナス値の場合は最新データのみ取得します。
		(通信が有効な場合は、この命令によってサーバーとの通信が発生します。
		この命令の終了までには、ある程度の時間がかかることを想定して
		プログラムを作成してください。)
		コメントは、設定する文字列の情報を256byte(半角255文字)までの
		内容で指定することができます。
		オプション機能値を省略するか、または0を指定した場合は、
		通常のランキング(スコアが高い順)としてデータを更新します。
		オプション値に、0x1000(4096)を指定した場合にはp1で指定した
		インデックスのスコアをクリア(スコアを0にする)します。
		オプション値に、0x2000(8192)を指定した場合には、
		ユーザー名の反映を行なわず、常に空の文字列が設定されます。
		オプション値は複数の値を加算して指定することが可能です。
		(データの内容をクリアする場合には、オプション値0x1000及び
		0x2000を組み合わせて使用してください。)


	hsptv_getrank var1,var2,var3,rank		ランキングデータ取得

		var1 : スコア情報が代入される変数名
		var2 : ユーザー名情報が代入される変数名
		var3 : コメント情報が代入される変数名
		rank : 順位のインデックス(0〜29)

		ランキングデータの内容を変数に読み出します。
		この命令は、hsptv_up命令によって更新されたデータを
		変数に読みだすものです。
		読み出される内容は、最後にhsptv_up命令を実行した
		時点の情報になります。
		rankの値は、は0が1位、29が30位となります。
		var1は数値型、var2,var3は文字列型として初期化されます。
		この命令では、通信は発生しないので、情報の読み出しは
		即時に行なわれます。


	hsptv_getini var,id				ユーザー情報取得

		var : ユーザー情報が代入される変数名
		id  : ユーザー情報ID

		HSPTVAPPユーザー情報を取得して変数に代入します。
		idにより取得されるユーザー情報IDを指定します。

			  ID : 内容
			------------------------
			  0  : 名前
			  1  : ユーザーキー
			  2  : PROXYアドレス
			  3  : PROXYポート

		存在しない情報IDが指定された場合は、何も代入せずに終了します。


	hsptv_setini "string",id			ユーザー情報設定

		"string" : 設定する文字列
		id       : ユーザー情報ID

		HSPTVAPPユーザー情報を設定します。
		idにより取得されるユーザー情報IDを指定します。

			  ID : 内容
			------------------------
			  0  : 名前
			  1  : ユーザーキー
			  2  : PROXYアドレス
			  3  : PROXYポート

		存在しない情報IDが指定された場合は、何もせずに終了します。


	hsptv_saveini					ユーザー情報保存

		ユーザー情報データをファイルとして保存します。
		ユーザー情報は、dllのあるフォルダに設定ファイルとして
		「hsptvapp.ini」を作成して保存します。
		この設定ファイルの内容は、起動時に自動的に読み込まれます。


・サーバー送信について

	実際にサーバー上から配信された場合は、ランキング情報の登録、取得に
	ネットワーク通信が行なわれます。
	最初に情報を送信する前には、「現在の情報をHSPTVサーバーに反映させて
	いいですか？」というダイアログが表示され、「はい」を選択した時のみ
	送信が行なわれます。
	(テストの段階では、「以上の情報を反映させていいですか？」という
	ダイアログが表示されます。)

	サーバーとの通信は、ネットワークの負荷や環境によって時間がかかる場合が
	あります。ある程度の時間がかかることを想定したプログラムを作成して
	おいてください。リアルタイムにデータを更新するようなプログラムは、
	作成できません。また、サーバーの負荷を抑えるためにも、５秒に１回の
	アクセス以上の頻度にならないように心掛けて下さい。
	必要以上にサーバー負荷がかかるプログラムの登録は、ネットワーク帯域
	確保のため、やむを得ず一時的に休止させて頂く場合もありますので、
	予めご了承下さい。

	サーバーとの通信は、httpプロトコルによって行なわれます。
	通信の際に設定されたPROXYサーバーが使用されます。

	HSPTVサーバー側に保持されたランキング情報は、基本的に配信される
	ソフトウェアごとに独立して管理され、対応したソフトウェア以外から
	アクセスされることはありません。
	HSPTVサーバーは、可能な限りランキング情報についての保持と管理を
	行ないますが、あくまでも現状をサービスとするもので、内容についての
	保証をするものではありません。
	事故やアップデートなどにより、やむを得ず、すべての情報が破棄される
	可能性がありますので、予めご了承下さい。


・サンプルスクリプトについて

	サンプルディレクトリhsptvappに「hsptv_test.hsp」として、サンプルスクリプトが
	収録されています。
	このスクリプトは、上位10名の情報表示と更新を行なうことができます。
	また、ユーザー情報を設定し保存することが可能です。


・再受信可能な文字列について

	HSPTVランキングサーバーとの通信は、文字列を別なコードにエンコードした後に
	行なわれます。日本語を含む、ほとんどの文字列は送信可能ですが、
	全角文字や特殊文字の一部で文字化けが発生する可能性があります。
	また、「&」記号は送信の段階で別な文字に変換されるため、
	正常な結果が期待できません。バイナリデータを文字列に変換する場合などは
	特に注意するようにしてください。


・今後のバージョンアップ予定

	HSPTVAPPは、ネットワークを介したユーザーデータの統合的なサービスを目指して
	様々な機能を追加していきたいと考えています。
	今後のバージョンアップ予定として以下のような機能を検討中です。

	■ランキング保持数の増加
	　(システムの負荷などを勘案しながらより多くのランキング保持を目指します)
	■ユーザーデータの保持
	　(ユーザーごとに小容量のデータ保存領域を用意し、クラウドシステムを構築します)
	■サーバーアイテム管理
	　(ユーザーが保持できるアイテムをサーバーが生成管理できる機能を提供します)


・更新履歴

	2013/03/08 ver0.9

		最初のバージョン。


・注意点

	HSPTVAPPによりプログラムを作成する場合は、サーバーから提供されたHSPTVAPP ID及びスタートアップコードを
	慎重に管理し、不正利用されることのないよう厳重に管理保管してください。
	スタートアップコードが外部に漏洩した場合、他のユーザーが不正にランキングにアクセスできる状態に
	なってしまいます。
	スクリプト中に「hsptv_start "スタートアップコード"」の形式で記述していれば、実行ファイルに変換時に
	暗号化されるので通常は問題ありません。スタートアップコードの文字列を外部ファイルや、レジストリ等に
	保存しないよう注意してください。
	HSPTVAPPは、HSPオフィシャルサイトであるHSPTV!サーバーとの連携によってサービスを運用しています。
	HSPTV!の管理者は、迷惑行為、虚偽の申請、不適切な行動がユーザーにあった場合に、やむを得ずHSPTV!管理者の
	判断で、HSPTVAPP IDアカウント停止、およびSoupSeedユーザ権利の剥奪を行なう場合がありますのでご了承下さい。
	また、HSPTV!の管理者は、各種メンテナンス等の為に、ユーザーに予告なくシステムの運用を停止、変更することが
	あります。HSPTVAPPは無保証のサービスです。HSPTV!の管理者は、HSPTVAPPで生じた故意、過失に関わらず如何なる損失、
	損害に対しても、一切の責任を負うことができません。利用するユーザーの責任に置いて運用を行なってください。
	HSPTV!及びSoupSeed管理者は、事前の許可なしに第三者に個人情報を開示することはありません。
	(法的な問題が発生し政府機関からの要請があり、管理者が必要と判断した場合を除く)

	HSPTVAPP.DLLは、HSP3と同時に使用されるプラグインファイルです。
	使用するHSPは、ver3.0以上をお使い下さい。ver2.61やそれ以前のHSPには
	対応していませんのでご注意下さい。
	EXEファイルを作成した場合でも、HSPTVAPP.DLLをEXEファイルと同じディレクトリ
	に置かないと動作しません。また、packfileにDLLを追加することはできません。


・著作権およびライセンス

	HSPTVAPPサービス及びプラグインは、onion softwareの著作物です。
	onion softwareは本プログラムによって生じた、いかなる損害についても
	保証いたしません。自己の責任の範囲で使用してください。

	HSPTVAPPプラグイン及びアーカイブは、BSDライセンスのもと、自由に改編、再配布を
	行なうことができます。


-------------------------------------------------------------------------------
                                                HSP users manual / end of file 
-------------------------------------------------------------------------------
