doclib\hsptv_api.txt » Plain Format
------------------------------------------------------------------------------ HSPTV API ver3.1 REFERENCE MANUAL HSP : Hot Soup Processor HSP拡張モジュールリファレンス copyright 2007 (c) onion software ------------------------------------------------------------------------------ ・はじめに ここでは、Hot Soup Processor ver3.1以降でサポートされている、 HSPTVブラウザに対応したプログラム作成についての解説と、付属の モジュールについての説明を行ないます。 HSPTV APIを使用することにより、HSPTV上で動作するプログラムの テストと、ランキング作成などの機能が利用可能です。 ・使い方の概要 HSPTV対応プログラムのテストには、スクリプトの先頭に以下の行を追加 してください。 #include "hsptv.as" これで、HSPTV上での動作チェックと、ランキング機能が利用できるように なります。 また、スクリプトの実行を行なうと、HSPTVブラウザが起動し動作します。 ・ランキング機能について HSPTV対応プログラムは、ランキング情報を保持する機能を利用することが できます。これは、動作しているソフトに対して「スコア」「ユーザー名」 「コメント」等の情報を一定量保存しておくもので、ゲームのハイスコア 情報などを記録するなど様々な用途に使用できます。 ランキング機能で保存される情報は、以下の通りです。 ■スコア 32bitの整数値。マイナス値は扱えません。 スコアの値が大きい順に上位30位が保持されます。 ■ユーザー名 スコアに付随するデータです。 スコアを登録したユーザー名の情報を文字列で保持します。 ユーザー名は、HSPTVブラウザのオプションで設定された 名前が自動的に使用されます。(英文字のみ20字まで) ■コメント スコアに付随するデータです。 スコアを登録したユーザーのコメント(付加情報)を 文字列で保持します。 この項目は、登録時のコメントに利用するだけでなく、 ソフトに関する情報を付加するなどプログラム側で自由に 利用することが可能です。 コメントには最大64文字までの文字列を保持できます。 実際に、HSPTVサーバーにプログラムが登録され、HSPTVブラウザにネットから 配信された場合には、スコア情報はサーバーに保持され、ユーザーの情報を 記録するインターネットランキングとして機能します。 HSPTV対応プログラム作成のためにテストしている状態(スクリプトエディタ から実行している時)では、カレントディレクトリにスコア情報を保持する ためのローカルファイル(hsptvdat.txt)が作成され、サーバーに登録される 時と同じ状態をシミュレートします。 (テストの段階では、HSPTVサーバーに情報は送信されません。) ユーザーが作成したプログラムでは、「スコア」「ユーザー名」「コメント」 の情報を自由に取得、更新することができます。 ハイスコアの保持に使用することはもちろん可能ですし、他の情報を保持 するために応用することもできます。 サーバーでは、スコアの値が大きい順に最大30件までデータを記録して いますが、プログラム側が何件まで表示するか、どの項目を表示するか、 またスコアの値を決める方法も任されています。 ランキング機能を利用するプログラムを作成する場合には、このドキュメント に記載されている「サーバー送信について」の項目をお読み頂き、同意された 上で開始してください。 ・追加命令について 「hsptv.as」を利用することで、以下の命令を新規に使用できるように なります。 hsptv_up p1,"comment", p2 HSPTVデータ更新 p1 : スコア値(32bit整数値) "comment" : コメント文字列(64byteまで) p2 : オプション機能値 HSPTVデータを更新します。 スコア,コメント情報を反映させます。 スコアがマイナス値の場合は最新データのみ取得します。 (HSPTV配信プログラムの場合は、この命令によってサーバー との通信が発生します。この命令の終了までには、ある程度の 時間がかかることを想定してプログラムを作成してください。) コメントは、設定する文字列の情報を64byteまでの内容で 指定することができます。 オプション機能値を省略するか、または0を指定した場合は、 通常のランキング(スコアが高い順)としてデータを更新します。 オプション値に、0x1000(4096)を指定した場合にはp1で指定した インデックスのスコアをクリア(スコアを0にする)します。 オプション値に、0x2000(8192)を指定した場合には、 ユーザー名の反映を行なわず、常に空の文字列が設定されます。 オプション値は複数の値を加算して指定することが可能です。 (データの内容をクリアする場合には、オプション値0x1000及び 0x2000を組み合わせて使用してください。) hsptv_getrank var1,var2,var3,rank HSPTVデータ取得 var1 : スコア情報が代入される変数名 var2 : ユーザー名情報が代入される変数名 var3 : コメント情報が代入される変数名 rank : 順位のインデックス(0〜29) HSPTVデータの内容を変数に読み出します。 この命令は、hsptv_up命令によって更新されたデータを 変数に読みだすものです。 読み出される内容は、最後にhsptv_up命令を実行した 時点の情報になります。 rankの値は、は0が1位、29が30位となります。 var1は数値型、var2,var3は文字列型として初期化されます。 この命令では、通信は発生しないので、情報の読み出しは 即時に行なわれます。 ・サーバー送信について 実際にサーバー上から配信された場合は、ランキング情報の登録、取得に ネットワーク通信が行なわれます。 最初に情報を送信する前には、「現在の情報をHSPTVサーバーに反映させて いいですか?」というダイアログが表示され、「はい」を選択した時のみ 送信が行なわれます。 (テストの段階では、「以上の情報を反映させていいですか?」という ダイアログが表示されます。) サーバーとの通信は、ネットワークの負荷や環境によって時間がかかる場合が あります。ある程度の時間がかかることを想定したプログラムを作成して おいてください。リアルタイムにデータを更新するようなプログラムは、 作成できません。また、サーバーの負荷を抑えるためにも、5秒に1回の アクセス以上の頻度にならないように心掛けて下さい。 必要以上にサーバー負荷がかかるプログラムの登録は、ネットワーク帯域 確保のため、やむを得ず一時的に休止させて頂く場合もありますので、 予めご了承下さい。 サーバーとの通信は、httpプロトコルによって行なわれます。 PROXYサーバー等の設定は、HSPTVブラウザの設定がそのまま使用されます。 HSPTVサーバー側に保持されたランキング情報は、基本的に配信される ソフトウェアごとに独立して管理され、対応したソフトウェア以外から アクセスされることはありません。 HSPTVサーバーは、可能な限りランキング情報についての保持と管理を 行ないますが、あくまでも現状をサービスとするもので、内容についての 保証をするものではありません。 事故やアップデートなどにより、やむを得ず、すべての情報が破棄される 可能性がありますので、予めご了承下さい。 ・サンプルスクリプトについて サンプルディレクトリに「hsptv_test.hsp」として、以下のスクリプトが 収録されています。 このスクリプトは、上位10名の情報表示と更新を行なうことができます。 #include "hsptv.as" score=1000 sdim comm,64 mes "HSPTVデータの更新登録テスト" hsptv_up -1,"" ; 最初に情報を更新しておく gosub *update ; ランキング情報の表示 pos 500,32:objsize 120,24 mes "スコア" input score mes "コメント" input comm button "更新",*send button "終了",*ok stop *send hsptv_up score, comm gosub *update stop *ok end *update color 255,255,255 boxf 0,32,500,480 ; 背景をクリア color 0,0,0 pos 0,32 repeat 10 ; 上位10位のみ表示 hsptv_getrank rscore,ruser,rcomm,cnt ; 情報を取得する rank=cnt+1 mes "#"+rank+":"+rscore+"("+ruser+") " mes " コメント:"+rcomm loop return ・更新履歴 2007/7/28 ver3.1 正式版としてリリース。 2007/7/20 ver3.1RC1 最初のバージョン。 ・注意点 hsptv.asは、あくまでもHSPTVブラウザ上で動作するプログラムのテストに 利用するためのファイルです。hsptv.asを利用した状態で、実行ファイル 作成を行なうことはできません。 HSPTV対応プログラムは、セキュリティのため以下の機能を制限しています。 ・ファイルの削除機能(delete命令) ・マウスカーソルの表示コントロール(mouse -1によるカーソル消去) ・windowsなどシステムが使用するフォルダへのアクセス これらの機能は、HSPTV対応プログラムで使用しないようお願い致します。 使用した場合は、無効になるか、またはエラーとなります。 実際にHSPTVブラウザ上で配信されるプログラムは、HSPTVサーバーに 登録しなければ、他のユーザーに届きません。 HSPTVサーバーへの登録は、HSPプログラムコンテストなどHSPTVサイト上で 不定期に行なわれています。詳しくは、HSPTVサイトを参照してください。 ・著作権およびライセンス HSPTV及びhsptvモジュールは、onion softwareの著作物です。 onion softwareは本プログラムによって生じた、いかなる損害についても 保証いたしません。自己の責任の範囲で使用してください。 hsptvモジュール(hsptv.as)は、BSDライセンスのもと、自由に改編、再配布を 行なうことができます。 ------------------------------------------------------------------------------- HSP users manual / end of file -------------------------------------------------------------------------------