;
;	HSP help manager用 HELPソースファイル
;	(先頭が「;」の行はコメントとして処理されます)
;

%type
拡張命令
%ver
3.3
%note
hspsock.asをインクルードすること。
%date
2009/08/01
%author
onitama
%dll
hspsock
%url
http://hsp.tv/
%port
Win


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




%index
sockclose
ソケットを切断
%group
通信制御命令
%prm
p1
p1=0〜31(0) : ソケットID番号
%inst
接続されているソケットを切断します。
初期化したソケットは必ず sockclose命令で切断するようにしてください。
%href
sockopen
sockmake




%index
sockput
データを送信
%group
通信制御命令
%prm
"message",p1
"message"   : 送信するメッセージ
p1=0〜31(0) : ソケットID番号
%inst
ソケットにデータを送信します。 "message"で指定した文字列か、または文字列型変数の内容をそのまま送信します。
^
送信中にエラーが発生した場合は、システム変数 statに0以外の値が代入されます。
%href
sockputc
sockputb




%index
sockputc
データを1byte送信
%group
通信制御命令
%prm
p1,p2
p1=0〜255(0) : 送信するメッセージ(1byte)
p2=0〜31(0)  : ソケットID番号
%inst
ソケットにデータを送信します。p1で指定した数値を1byte送信します。
^
送信中にエラーが発生した場合は、システム変数 statに0以外の値が代入されます。
%href
sockput
sockputb




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



%index
sockcheck
データの到着を調べる
%group
通信制御命令
%prm
p1
p1=0〜31(0) : ソケットID番号
%inst
指定したソケットに sockget系の命令で取得できるデータが到着しているかどうか調べます。
受信可能なデータがある場合は、システム変数 statに0が代入されます。データが到着していない場合は、システム変数statは1になります。
^
通信エラーなどが起こった場合は、システム変数 statは2以上の値になります。エラーが起こった場合は、通信を行なうことはできません。
^
システム変数statの値の詳細は以下の通りです。
^p
  stat : 内容
 ---------------------------------------------------
   0   : 受信データが到着している
   1   : 受信データは到着していない(タイムアウト)
   2   : 通信中にエラーが発生した
^p
sockcheckはデータの到着を調べるだけです。 実際のデータを取得するには、sockget, sockgetc, sockgetbなどの命令で受信する必要があります。
%href
sockget
sockgetc
sockgetb



%index
sockget
データを受信
%group
通信制御命令
%prm
p1,p2,p3
p1=変数     : 受信内容が格納される変数名
p2=0〜(64)  : 受信サイズ(byte単位)
p3=0〜31(0) : ソケットID番号
%inst
ソケットからデータを受信し、p1で指定した文字列型の変数に内容を代入します。p2で最大受信サイズを指定します。
^
受信中にエラーが発生した場合は、システム変数 statに0以外の値が代入されます。
%href
sockgetc
sockgetb




%index
sockgetc
データを1byte受信
%group
通信制御命令
%prm
p1,p2
p1=変数     : 受信内容が格納される変数名
p2=0〜31(0) : ソケットID番号
%inst
ソケットからデータを 1byte受信し、p1で指定した数値型の変数に内容を代入します。
^
受信中にエラーが発生した場合は、システム変数 statに0以外の値が代入されます。
%href
sockget
sockgetb




%index
sockgetb
バッファにデータを受信
%group
通信制御命令
%prm
p1,p2,p3,p4
p1=変数 : 受信内容が格納される変数名
p2=0〜(0)   : バッファオフセット (byte単位)
p3=0〜(64)  : 受信サイズ (byte単位)
p4=0〜31(0) : ソケットID番号
%inst
ソケットからデータを受信し、p1で指定した変数バッファに内容をバイナリデータとして格納します。
p1で指定される変数は、文字列型、数値型のどちらでも構いません。変数が確保しているメモリに直接受信内容を読み込みます。
^
p2で、格納されるバッファのオフセットを指定できます。
たとえば、p2が100の場合は、先頭から100byte目から受信データを格納することになります。p2が省略された場合は0になります。
^
p3で最大受信サイズを指定します。
受信サイズを指定する場合は、変数バッファに指定したサイズを格納できるだけのメモリが、あらかじめ確保されていなければなりません。
p3が省略されるか、0の場合は、64(byte)が指定されます。
^
sockgetb命令の実行後は、システム変数statに実際に受信されたサイズ(byte)が代入されます。システム変数 statの内容が0だった場合は、通信エラー、もしくはタイムアウトでまったく受信されていないことを示しています。
(変数バッファの内容は、peek命令、poke命令などで操作することが可能です)
%href
sockget
sockgetc




%index
sockmake
ソケットをサーバーとして初期化
%group
通信制御命令
%prm
p1,p2
p1=0〜31(0) : ソケットID番号
p2=0〜(0)   : ポート番号
%inst
ソケットを初期化してサーバーとして使用できるようにします。
p1でソケットID番号を指定します。
p2で、ポート番号を指定します。既にシステムで予約されているソケット番号は使用できません。独自のプロトコルを定義する場合は、1024以降の番号を使うようにするといいでしょう。
^
sockmake命令が実行されると、サーバーとしての準備が整います。
この後、実際にクライアントと接続するためには、sockwait命令でクライアントの接続が完了するまで待つ必要があります。
^
結果がエラーの場合は、 0以外の値になります。初期化でエラーが起こった場合は、通信を行なうことはできません。

システム変数 statの値の詳細は以下の通りです。
^p
  stat : エラー内容
 ----------------------------------------------------
   1   : TCP/IPがWindowsにインストールされていない
   2   : ソケットの初期化に失敗した
   3   : Socketのバインドに失敗した
^p
%href
sockwait
sockopen
sockclose




%index
sockwait
クライアントの着信を待つ
%group
通信制御命令
%prm
p1
p1=0〜31(0) : ソケットID番号
%inst
sockmake命令でサーバーとして準備されたソケットで、クライアントの着信を待ちます。
sockwait命令は、必ずsockmake命令が正常に終了した後に実行される必要があります。
^
sockwait命令は、クライアントの着信がない場合や、エラーが発生した場合には、システム変数 statに0以外の値を返します。
システム変数 statに0が代入された場合にはじめてクライアントとの接続に成功し、sockget命令、sockput命令などの通信を行なうことができるようになります。
^
サーバーとして着信を待つ場合には、sockmake命令でソケットをサーバーとして初期化した後、sockwait命令でシステム変数 statが0になるまでループして待機して下さい。その際には、必ずループ内に waitやawait命令を入れて間をあける必要があります。
そうしないと、 Windowsの他のアプリケーションにタスクが回らなくなってしまいます。
^
結果がエラーの場合は、 0以外の値になります。エラーが起こった場合は、通信を行なうことはできません。

システム変数 statの値の詳細は以下の通りです。
^p
  stat : エラー内容
 -----------------------------------------------------
   1   : クライアントから接続要求が来ていない
   2   : sockmake命令でサーバーの準備ができていない
   3   : Socketが受信状態になっていない
   4   : Socketを受信状態にするのに失敗した
   5   : クライアントとの接続に失敗した
^p
%href
sockmake




%index
ipget
ホストのIPアドレスを取得
%group
通信制御命令
%prm
%inst
ホストのIPアドレスを取得して、システム変数refstrに代入します。
^
IPアドレスを取得する際にエラーが発生すると、システム変数 statに1が代入されます。正常にIPアドレスが取得できた場合には、システム変数statの値は0になります。




