------------------------------------------------------------------------------
HSPSOCK ver3.2   REFERENCE MANUAL                   HSP : Hot Soup Processor  
ＨＳＰ拡張DLLリファレンス             copyright 1999-2009 (c) onion software  
------------------------------------------------------------------------------

・はじめに

	このDLLは、Hot Soup Processor ver3.2以降とともに使用することで、様々な
	機能拡張を行なうことのできるプラグインモジュールです。
	この拡張DLLを使用することにより、新規命令が追加され、TCP/IPソケット通信
	の機能がHSPからコントロールできるようになります。
	これらの命令は、HSP単体では実現できないようなツール、ユーティリティの
	作成に役立つものが多く、さらに高度なアプリケーション開発が可能になります。


・インストール

	拡張プラグインのファイル、HSPSOCK.DLLは、HSED3.EXEおよび、HSP3.EXEのある
	ディレクトリと同じ場所に置いてください。
	(実行に使われているHSP3.EXEと同じディレクトリに、HSPSOCK.DLLがない場合は
	エラーになります)
	また、スクリプトを作成する場合には、HSPSOCK.ASをスクリプトと同じディレク
	トリに置き、スクリプトの先頭に必ず「#include "hspsock.as"」という行を追加
	してください。以上で、HSPの機能が拡張され、このリファレンスで説明を
	している命令を使用することができるようになります。
	まず最初に、試しに付属のサンプルスクリプトを実行してみてください。
	拡張された機能の簡単な使用例を見ることができるはずです。


・注意点

	HSPSOCK.DLLは、HSP3.EXEと同時に使用されるプラグインファイルです。
	EXEファイルを作成した場合でも、HSPSOCK.DLLをEXEファイルと同じディレクトリ
	に置かないと動作しません。また、packfileにDLLを追加することはできません。


・著作権および連絡先

	ユーザーがHSPを使って作成したオリジナルのソフトウェア(実行ファイル)の
	権利は、それを作成したユーザーに属します。
	有償・無償を問わずHSPSOCK.DLLを自由に配布することができ、onion softwareの
	著作権表示義務もありません。
	ユーザーが作成したオリジナルのソフトウェアに対してonion softwareが著作権を
	主張することはありません。

	HSPSOCKプラグインは、onion softwareの著作物です。
	onion softwareは本プログラムによって生じた、いかなる損害についても
	保証いたしません。自己の責任の範囲で使用してください。
	HSPDB.DLLは、Microsoft Visual C++ 7.1でコンパイルされて います。 


・命令一覧

	sockopen p1,"url",p2			ソケットを初期化して接続
	sockclose p1					ソケットを切断
	sockput "message",p1			データを送信
	sockputc p1,p2					データを1byte送信
	sockputb p1,p2,p3,p4			バッファのデータを送信
	sockget p1,p2,p3				データを受信
	sockgetc p1,p2					データを1byte受信
	sockgetb p1,p2,p3,p4			バッファにデータを受信
	sockmake p1,p2					ソケットをサーバーとして初期化
	sockwait p1,p2					クライアントの着信を待つ
	sockcheck p1				データ到着を調べる
	ipget							ホストのIPアドレスを取得


・TCP/IPソケット通信命令

	LANや、ppp経由のインターネットとの通信を行なうための命令セットです。
	インターネットに限らず、TCP/IPプロトコルで繋がれたネットワークにソケットを
	使ってアクセスすることができます。
	これにより、HTTP、FTP、TELNETなどのクライアントを作成することが可能です。
	現在のバージョンでは、非同期通信および、サーバー機能はサポートされて
	いません。

	TCP/IP通信を行なう際には、必ず最初に初期化をする必要があります。
	サーバーとして初期化する場合は、sockmake命令を、クライアントとして
	初期化する場合は、sockopen命令を使用します。
	いずれの場合も通信が終わったら必ずsockclose命令で切断しなければなりません。
	また、ソケットには0〜31までのIDがあり、同時に複数のソケットを使うことが
	できます。
	TCP/IP通信の詳細および、プロトコルについては専門の書籍やドキュメントを
	参照してください。


	sockopen p1,"url",p2			ソケットを初期化して接続

	p1=0〜31(0)  : ソケットID番号
	"url"       : URL指定文字列
	p2=0〜(0)   : ポート番号

	・説明

		ソケットを初期化して使用できるようにします。
		TCP/IP通信を行ない際には、必ず最初に初期化して相手のサーバー
		に接続しなければなりません。
		p1でソケットID番号を指定します。
		"url"で接続先のURLを文字列で指定します。これは、「www.yahoo.co.jp」
		のようなドメイン名か、「202.132.50.7」のようなIPアドレスを直接
		指定したもののどちらでもかまいません。
		「http://」や「ftp://」のようなスキーム名は入れないでください。
		p2で、接続するポート番号を指定します。これは、どのようなサーバー
		に接続するかによって違います。オリジナルのポートを作成する場合は、
		1024以降を使用するようにしてください。
		sockopen命令が実行された結果が、システム変数statに代入されます。
		結果がエラーの場合は、0以外の値になります。初期化でエラーが起こった
		場合は、通信を行なうことはできません。
		システム変数statの値の詳細は以下の通りです。

		  stat    エラー内容
		  --------------------------------
		   1    : TCP/IPがWindowsにインストールされていない
		   2    : ソケットの初期化に失敗した
		   3    : URLのサーバー名取得に失敗した
		   4    : サーバーに接続できなかった

	sockclose p1				ソケットを切断

	p1=0〜31(0)  : ソケットID番号

	・説明

		接続されているソケットを切断します。
		初期化したソケットは必ずsockclose命令で切断するようにして
		ください。

	sockput "message",p1			データを送信

	"message"   : 送信するメッセージ
	p1=0〜31(0)  : ソケットID番号

	・説明

		ソケットにデータを送信します。"message"で指定した文字列か、
		または文字列型変数の内容をそのまま送信します。
		送信中にエラーが発生した場合は、システム変数statに0以外の
		値が代入されます。

	sockputc p1,p2				データを1byte送信

	p1=0〜255(0) : 送信するメッセージ(1byte)
	p2=0〜31(0)   : ソケットID番号

	・説明

		ソケットにデータを送信します。p1で指定した数値を1byte送信
		します。送信中にエラーが発生した場合は、システム変数statに
		0以外の値が代入されます。

	sockputb p1,p2,p3,p4		バッファのデータを送信

	p1=変数     : 送信内容が格納されている変数名
	p2=0〜(0)   : バッファオフセット(byte単位)
	p3=0〜(64)  : 送信サイズ(byte単位)
	p4=0〜31(0)  : ソケットID番号

	・説明

		p1で指定した変数バッファの内容をバイナリデータとしてソケットに
		送信します。
		p1で指定される変数は、文字列型、数値型のどちらでも構いません。
		変数が確保しているメモリの内容が直接送信されます。
		p2で、変数バッファのオフセットを指定できます。
		たとえば、p2が100の場合は、先頭から100byte目からの内容を送信する
		ことになります。p2が省略された場合は0になります。
		p3で送信サイズを指定します。
		送信サイズは、変数バッファにあらかじめ確保されているサイズ以内で
		なければなりません。
		p3が省略されるか、0の場合は、64(byte)が指定されます。
		sockputb命令が実行後は、システム変数statに、実際に送信された
		サイズ(byte)が代入されます。システム変数statの内容が0だった
		場合は、通信エラー、もしくはタイムアウトでまったく送信されて
		いないことを示しています。
		(変数バッファの内容は、peek関数、poke命令などで操作することが
		可能です。)

	sockget p1,p2,p3			データを受信

	p1=変数     : 受信内容が格納される変数名
	p2=0〜(64)  : 受信サイズ(byte単位)
	p3=0〜31(0)  : ソケットID番号

	・説明

		ソケットからデータを受信し、p1で指定した文字列型の変数に
		内容を代入します。p2で最大受信サイズを指定します。
		受信中にエラーが発生した場合は、システム変数statに0以外の
		値が代入されます。

	sockgetc p1,p2				データを1byte受信

	p1=変数     : 受信内容が格納される変数名
	p3=0〜31(0)  : ソケットID番号

	・説明

		ソケットからデータを1byte受信し、p1で指定した数値型の変数に
		内容を代入します。
		受信中にエラーが発生した場合は、システム変数statに0以外の
		値が代入されます。

	sockgetb p1,p2,p3,p4		バッファにデータを受信

	p1=変数     : 受信内容が格納される変数名
	p2=0〜(0)   : バッファオフセット(byte単位)
	p3=0〜(64)  : 受信サイズ(byte単位)
	p4=0〜31(0)  : ソケットID番号

	・説明

		ソケットからデータを受信し、p1で指定した変数バッファに
		内容をバイナリデータとして格納します。
		p1で指定される変数は、文字列型、数値型のどちらでも構いません。
		変数が確保しているメモリに直接受信内容を読み込みます。

		p2で、格納されるバッファのオフセットを指定できます。
		たとえば、p2が100の場合は、先頭から100byte目から受信データを
		格納することになります。p2が省略された場合は0になります。
		p3で最大受信サイズを指定します。
		受信サイズを指定する場合は、変数バッファに指定したサイズを格納
		できるだけのメモリが、あらかじめ確保されていなければなりません。
		p3が省略されるか、0の場合は、64(byte)が指定されます。
		sockgetb命令が実行後は、システム変数statに、実際に受信された
		サイズ(byte)が代入されます。システム変数statの内容が0だった
		場合は、通信エラー、もしくはタイムアウトでまったく受信されて
		いないことを示しています。
		(変数バッファの内容は、peek命令、poke命令などで操作することが
		可能です。)

	sockmake p1,p2				ソケットをサーバーとして初期化

	p1=0〜31(0)  : ソケットID番号
	p2=0〜(0)   : ポート番号

	・説明

		ソケットを初期化してサーバーとして使用できるようにします。
		p1でソケットID番号を指定します。
		p2で、ポート番号を指定します。既にシステムで予約されているソケット
		番号は使用できません。独自のプロトコルを定義する場合は、1024以降の
		番号を使うようにするといいでしょう。
		sockmake命令が実行されると、サーバーとしての準備が整います。
		この後、実際にクライアントと接続するためには、sockwait命令で
		クライアントの接続が完了するまで待つ必要があります。

		結果がエラーの場合は、0以外の値になります。初期化でエラーが起こった
		場合は、通信を行なうことはできません。
		システム変数statの値の詳細は以下の通りです。

		  stat    エラー内容
		  --------------------------------
		   1    : TCP/IPがWindowsにインストールされていない
		   2    : ソケットの初期化に失敗した
		   3    : Socketのバインドに失敗した


	sockwait p1					クライアントの着信を待つ

	p1=0〜31(0)  : ソケットID番号

	・説明

		sockmake命令でサーバーとして準備されたソケットで、クライアント
		の着信を待ちます。sockwait命令は、必ずsockmake命令が正常に終了
		した後に実行される必要があります。

		sockwait命令は、クライアントの着信がない場合や、エラーが発生
		した場合には、システム変数statに0以外の値を返します。
		システム変数statに0が代入された場合にはじめてクライアントとの
		接続に成功し、sockget命令、sockput命令などの通信を行なうことが
		できるようになります。

		サーバーとして着信を待つ場合には、sockmake命令でソケットを
		サーバーとして初期化した後、sockwait命令でシステム変数statが
		0になるまでループして待機して下さい。その際には、必ずループ内に
		waitやawait命令を入れて間をあける必要があります。
		そうしないと、Windowsの他のアプリケーションにタスクが回らなく
		なってしまいます。

		結果がエラーの場合は、0以外の値になります。エラーが起こった
		場合は、通信を行なうことはできません。
		システム変数statの値の詳細は以下の通りです。

		  stat    エラー内容
		  --------------------------------
		   1    : クライアントから接続要求が来ていない
		   2    : sockmake命令でサーバーの準備ができていない
		   3    : Socketが受信状態になっていない
		   4    : Socketを受信状態にするのに失敗した
		   5    : クライアントとの接続に失敗した


	ipget						ホストのIPアドレスを取得

	・説明

		ホストのIPアドレスを取得して、システム変数refstrに代入します。
		IPアドレスを取得する際にエラーが発生すると、システム変数statに
		1が代入されます。正常にIPアドレスが取得できた場合には、システム
		変数statの値は0になります。


	sockcheck p1					データの到着を調べる

	p1=0〜31(0)  : ソケットID番号

	・説明

		指定したソケットにsockget系の命令で取得できるデータが到着
		しているかどうか調べます。
		受信可能なデータがある場合は、システム変数statに0が代入され
		ます。データが到着していない場合は、システム変数statは1に
		なります。

		通信エラーなどが起こった場合は、システム変数statは2以上の値に
		なります。エラーが起こった場合は、通信を行なうことはできません。

		システム変数statの値の詳細は以下の通りです。

		  stat    内容
		  --------------------------------
		   0    : 受信データが到着している
		   1    : 受信データは到着していない(タイムアウト)
		   2    : 通信中にエラーが発生した

		sockcheckはデータの到着を調べるだけです。実際のデータを
		取得するには、sockget, sockgetc, sockgetbなどの命令で受信
		する必要があります。


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